feat: install repo-aware lnk cli

Author: bhdicaire

README.md

@@ -62,15 +62,14 @@ The CLI intentionally documents only the user-facing environment flags:
 
 * `DRY_RUN=true` prints the planned change without writing, committing, or
   pushing.
-* `LNK_OWNER=OWNER` changes the default owner field for new links.
-* `V8S_LINKS_FILE=FILE` overrides the links file. `LNK_FILE` is supported
-  as a legacy alias.
+* `V8S_REPO=PATH` points copied local helpers at the local repository path.
+* `V8S_LINKS_OWNER=OWNER` changes the default owner field for new links.
+* `V8S_LINKS_FILE=FILE` overrides the links file.
 * `V8S_SCHEDULES_FILE=FILE` overrides the schedule file.
-* `V8S_POLICY_FILE=FILE` overrides the block policy file. `BLOCKLIST_FILE`
-  is supported as a legacy alias.
+* `V8S_POLICY_FILE=FILE` overrides the block policy file.
 
-Successful write operations commit and push automatically so Cloudflare can
-deploy the generated site.
+Successful write operations run `npm run check`, then commit and push
+automatically so Cloudflare can deploy the generated site.
 
 ## Limitations
 

defaults/v8s-local-config.json

@@ -5,6 +5,9 @@
     "install_path": "$XDG_CONFIG_HOME/zsh/v8s.sh",
     "rc_file": "$XDG_CONFIG_HOME/zsh/.zshrc"
   },
+  "link_cli": {
+    "install_path": "$XDG_CONFIG_HOME/bin/lnk"
+  },
   "registry": {
     "local_path": "~/.v8s.json"
   },

scripts/blocklist-cli.mjs

@@ -2,8 +2,12 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { spawnSync } from "node:child_process";
 
-const POLICY_PATH = process.env.V8S_POLICY_FILE || process.env.BLOCKLIST_FILE || "custom/v8s-policies.json";
+const ROOT = process.env.V8S_REPO || process.cwd();
+process.chdir(ROOT);
+
+const POLICY_PATH = process.env.V8S_POLICY_FILE || "custom/v8s-policies.json";
 const CATEGORIES_PATH = "defaults/v8s-blocklist-categories.json";
 
 function usage() {
@@ -21,8 +25,8 @@ Options:
   --help                Show this help
 
 Environment:
+  V8S_REPO=PATH          Local vanityURLs/code repository path
   V8S_POLICY_FILE=FILE   Override the block policy file
-  BLOCKLIST_FILE=FILE    Legacy alias for V8S_POLICY_FILE
 
 Docs:
   https://www.VanityURLs.link/en/docs`);
@@ -40,6 +44,17 @@ function writeJson(path, value) {
   fs.writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
 }
 
+function run(command, args) {
+  const result = spawnSync(command, args, {
+    cwd: ROOT,
+    stdio: "inherit",
+    shell: process.platform === "win32"
+  });
+
+  if (result.error) throw result.error;
+  if (result.status !== 0) process.exit(result.status ?? 1);
+}
+
 function pathModuleDirname(filePath) {
   const dir = path.dirname(filePath);
   return dir === "." ? process.cwd() : dir;
@@ -126,13 +141,17 @@ function ensurePolicyShape(policy) {
   return policy;
 }
 
-function savePolicy(policy, dryRun) {
-  if (dryRun) {
+function savePolicy(policy, dryRun, message) {
+  if (dryRun || process.env.DRY_RUN === "true") {
     console.log(JSON.stringify(policy, null, 2));
     return;
   }
 
   writeJson(POLICY_PATH, policy);
+  run("npm", ["run", "check"]);
+  run("git", ["add", POLICY_PATH]);
+  run("git", ["commit", "-m", message]);
+  run("git", ["push"]);
 }
 
 function addBlock(domainInput, options) {
@@ -170,7 +189,7 @@ function addBlock(domainInput, options) {
   }
 
   policy.block_domains.sort((a, b) => a.domain.localeCompare(b.domain));
-  savePolicy(policy, options.dryRun);
+  savePolicy(policy, options.dryRun, `feat(policies): block ${domain}`);
 
   if (!options.dryRun) {
     console.log(`Blocked ${domain} as ${category}/${severity}`);
@@ -224,7 +243,7 @@ function addKeyword(keywordInput, options) {
     return aKeyword.localeCompare(bKeyword);
   });
 
-  savePolicy(policy, options.dryRun);
+  savePolicy(policy, options.dryRun, `feat(policies): block keyword ${keyword}`);
 
   if (!options.dryRun) {
     console.log(`Blocked keyword ${keyword} as ${category}/${severity}`);
@@ -259,7 +278,7 @@ function addAllow(domainInput, options) {
   policy.allow_domains = [...allowDomains.values()].sort((a, b) => a.domain.localeCompare(b.domain));
   policy.block_domains = policy.block_domains.filter((entry) => normalizeHostname(entry.domain) !== domain);
 
-  savePolicy(policy, options.dryRun);
+  savePolicy(policy, options.dryRun, `feat(policies): allow ${domain}`);
 
   if (!options.dryRun) {
     const suffix = options.reason ? ` (${options.reason})` : "";

scripts/lnk

@@ -4,7 +4,10 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import { spawnSync } from "node:child_process";
 
-const DEFAULT_OWNER = process.env.LNK_OWNER || "bhd";
+const ROOT = process.env.V8S_REPO || process.cwd();
+process.chdir(ROOT);
+
+const DEFAULT_OWNER = process.env.V8S_LINKS_OWNER || "bhd";
 const LINKS_FILE = resolveLinksFile();
 const VALID_STATES = new Set([
   "permanent",
@@ -45,21 +48,22 @@ Options:
   --help                 Show this help
 
 Files:
-  Links are written to custom/v8s-links.txt when it exists, otherwise defaults/v8s-links.txt.
+  Links are written to custom/v8s-links.txt unless V8S_LINKS_FILE overrides the path.
   Schedules are written to custom/v8s-schedules.json.
   Block policies are written to custom/v8s-policies.json.
 
 Environment:
   DRY_RUN=true           Print the planned change without writing, committing, or pushing
-  LNK_OWNER=OWNER        Default owner value for new links
-  V8S_LINKS_FILE=FILE    Override the links file; LNK_FILE is supported as a legacy alias
+  V8S_REPO=PATH          Local vanityURLs/code repository path
+  V8S_LINKS_OWNER=OWNER  Default owner value for new links
+  V8S_LINKS_FILE=FILE    Override the links file
   V8S_SCHEDULES_FILE=FILE
                          Override the schedule file
-  V8S_POLICY_FILE=FILE   Override the block policy file; BLOCKLIST_FILE is a legacy alias
+  V8S_POLICY_FILE=FILE   Override the block policy file
 
 Notes:
   Slugs may contain / to create API-like paths.
-  Successful write operations commit and push automatically.
+  Successful write operations run npm run check, then commit and push automatically.
 
 Examples:
   ./scripts/lnk https://github.com/vanityURLs github
@@ -76,9 +80,7 @@ Docs:
 
 function resolveLinksFile() {
   if (process.env.V8S_LINKS_FILE) return process.env.V8S_LINKS_FILE;
-  if (process.env.LNK_FILE) return process.env.LNK_FILE;
-  if (fs.existsSync("custom/v8s-links.txt")) return "custom/v8s-links.txt";
-  return "defaults/v8s-links.txt";
+  return "custom/v8s-links.txt";
 }
 
 function run(command, args) {
@@ -211,6 +213,11 @@ function appendLine(filePath, line) {
   fs.mkdirSync(dirname(filePath), {
     recursive: true
   });
+
+  if (!fs.existsSync(filePath)) {
+    fs.writeFileSync(filePath, "# slug|target|state|title|description|tags|owner|expires_at|notes\n");
+  }
+
   fs.appendFileSync(filePath, `${line}\n`);
 }
 
@@ -330,9 +337,7 @@ function saveScheduleConfig(filePath, config, dryRun, slug) {
   }
 
   writeJson(filePath, config);
-  run("git", ["add", filePath]);
-  run("git", ["commit", "-m", `feat(schedules): update ${slug}`]);
-  run("git", ["push"]);
+  finalizeChange(filePath, `feat(schedules): update ${slug}`);
 }
 
 function listSchedules(config, requestedSlug) {
@@ -503,8 +508,13 @@ function main() {
 
   appendLine(LINKS_FILE, line);
 
-  run("git", ["add", LINKS_FILE]);
-  run("git", ["commit", "-m", `feat(links): add ${slug}`]);
+  finalizeChange(LINKS_FILE, `feat(links): add ${slug}`);
+}
+
+function finalizeChange(filePath, message) {
+  run("npm", ["run", "check"]);
+  run("git", ["add", filePath]);
+  run("git", ["commit", "-m", message]);
   run("git", ["push"]);
 }
 

scripts/local-install.mjs

@@ -11,6 +11,7 @@ const ROOT = process.cwd();
 const DEFAULT_CONFIG_PATH = path.join(ROOT, "defaults", "v8s-local-config.json");
 const CUSTOM_CONFIG_PATH = path.join(ROOT, "custom", "v8s-local-config.json");
 const HELPER_SOURCE_PATH = path.join(ROOT, "scripts", "v8s.sh");
+const LNK_SOURCE_PATH = path.join(ROOT, "scripts", "lnk");
 const START_MARKER = "# >>> V8S >>>";
 const END_MARKER = "# <<< V8S <<<";
 
@@ -92,6 +93,10 @@ function mergeConfig(base, local) {
       ...(base.shell_helper || {}),
       ...(local.shell_helper || {})
     },
+    link_cli: {
+      ...(base.link_cli || {}),
+      ...(local.link_cli || {})
+    },
     registry: {
       ...(base.registry || {}),
       ...(local.registry || {})
@@ -118,6 +123,9 @@ async function promptConfig(config, args) {
       repository: {
         ...config.repository,
         path: config.repository?.path || ROOT
+      },
+      link_cli: {
+        ...config.link_cli
       }
     };
   }
@@ -131,6 +139,9 @@ async function promptConfig(config, args) {
         ...config.shell_helper,
         enabled
       },
+      link_cli: {
+        ...config.link_cli
+      },
       registry: {
         ...config.registry
       },
@@ -142,6 +153,7 @@ async function promptConfig(config, args) {
     if (!enabled) return next;
 
     next.shell_helper.install_path = await question(rl, "Shell helper install path", next.shell_helper.install_path);
+    next.link_cli.install_path = await question(rl, "lnk CLI install path", next.link_cli.install_path);
     next.shell_helper.rc_file = await question(rl, "Shell rc file to update", next.shell_helper.rc_file);
     next.registry.local_path = await question(rl, "Local registry path", next.registry.local_path);
     next.repository.path = await question(rl, "Local repository path", next.repository.path || ROOT);
@@ -182,23 +194,27 @@ function shellQuote(value) {
 
 function installHelper(config, args) {
   if (config.shell_helper?.enabled !== true) {
-    console.log("Shell helper disabled; local config written only.");
+    console.log("Shell helper disabled; installing lnk CLI only.");
+    installLnkCli(config, args);
     return;
   }
 
   const helperTarget = expandLocalPath(config.shell_helper.install_path);
+  const lnkTarget = expandLocalPath(config.link_cli?.install_path || "$XDG_CONFIG_HOME/bin/lnk");
   const rcFile = expandLocalPath(config.shell_helper.rc_file);
   const registryPath = expandLocalPath(config.registry?.local_path || "~/.v8s.json");
   const repoPath = expandLocalPath(config.repository?.path || ROOT);
 
   if (args.dryRun) {
     console.log(`[dry-run] would copy scripts/v8s.sh to ${helperTarget}`);
+    console.log(`[dry-run] would copy scripts/lnk to ${lnkTarget}`);
     console.log(`[dry-run] would update ${rcFile}`);
     return;
   }
 
   fs.mkdirSync(path.dirname(helperTarget), { recursive: true });
   fs.copyFileSync(HELPER_SOURCE_PATH, helperTarget);
+  copyExecutable(LNK_SOURCE_PATH, lnkTarget);
 
   const block = [
     START_MARKER,
@@ -218,9 +234,28 @@ function installHelper(config, args) {
 
   fs.writeFileSync(rcFile, next);
   console.log(`Installed V8S shell helper to ${helperTarget}`);
+  console.log(`Installed lnk CLI to ${lnkTarget}`);
   console.log(`Updated ${rcFile}`);
 }
 
+function installLnkCli(config, args) {
+  const lnkTarget = expandLocalPath(config.link_cli?.install_path || "$XDG_CONFIG_HOME/bin/lnk");
+
+  if (args.dryRun) {
+    console.log(`[dry-run] would copy scripts/lnk to ${lnkTarget}`);
+    return;
+  }
+
+  copyExecutable(LNK_SOURCE_PATH, lnkTarget);
+  console.log(`Installed lnk CLI to ${lnkTarget}`);
+}
+
+function copyExecutable(sourcePath, targetPath) {
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  fs.copyFileSync(sourcePath, targetPath);
+  fs.chmodSync(targetPath, 0o755);
+}
+
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }