@teurons/vds 0.0.2 → 0.0.4

package/README.md

@@ -4,7 +4,7 @@ The `vds` command. It starts, checks and indexes a VDS workspace on your machine
 
 VDS keeps a product's spec as files: capabilities that hold rules written in EARS,
 scenarios in Gherkin, and flows that point at those rules in order.
-This package is an early alpha and is published on the `next` tag.
+This package is an early alpha.
 
 ## Set it up with your AI agent
 
@@ -13,10 +13,10 @@ Copy this prompt into Claude Code, Codex or any coding agent, run from the root
 ```text
 Set up VDS in this project.
 
-1. Run `npx -y @teurons/vds@next init vds-workspace`. It creates the
+1. Run `npx -y @teurons/vds init vds-workspace`. It creates the
    capabilities, flows and scenarios folders, a VDS.md guide and a .vds.json.
    If it says a workspace already exists, stop and tell me what it found.
-2. Add `"vds": "vds"` to package.json scripts and @teurons/vds@next to
+2. Add `"vds": "vds"` to package.json scripts and @teurons/vds to
    devDependencies if this project uses npm, pnpm or yarn. Otherwise skip this.
 3. Read vds-workspace/VDS.md and follow it from now on whenever you work on
    the spec.
@@ -24,16 +24,17 @@ Set up VDS in this project.
    what exists) saying: the product spec lives in vds-workspace; read
    vds-workspace/VDS.md before changing it; run `vds index vds-workspace`
    first and `vds check vds-workspace` before finishing.
-5. Run `npx @teurons/vds@next check vds-workspace` and confirm it prints valid.
+5. Run `npx @teurons/vds check vds-workspace` and confirm it prints valid.
 6. Tell me what you created and changed, file by file.
 ```
 
 ## Commands
 
 ```sh
-npx @teurons/vds@next init [folder]    # start a workspace (never overwrites one)
-npx @teurons/vds@next check [folder]   # print every problem; exit 1 if any
-npx @teurons/vds@next index [folder]   # print the index: every flow and rule, one line each
+npx @teurons/vds init [folder]    # start a workspace (never overwrites one)
+npx @teurons/vds check [folder]   # print every problem; exit 1 if any
+npx @teurons/vds index [folder]   # print the index: every flow and rule, one line each
+npx @teurons/vds update [folder]  # install the newest vds, refresh VDS.md
 ```
 
 `folder` defaults to the current folder.

package/dist/vds.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/bin.js
-import { readdirSync, readFileSync as readFileSync2 } from "node:fs";
-import { join as join2, resolve } from "node:path";
+import { readdirSync, readFileSync as readFileSync4 } from "node:fs";
+import { join as join3, resolve } from "node:path";
 
 // ../../specs/js/load.js
 import { readFileSync } from "node:fs";
@@ -97,8 +97,18 @@ function loadMapper() {
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { createServer } from "node:net";
 import { join } from "node:path";
-var FOLDERS = ["capabilities", "flows", "scenarios"];
-var FIRST_PORT = 4600;
+
+// src/version.js
+import { readFileSync as readFileSync2 } from "node:fs";
+var baked = false ? null : "0.0.4";
+var VERSION = process.env.VDS_VERSION ?? baked ?? JSON.parse(readFileSync2(new URL("../package.json", import.meta.url), "utf8")).version;
+function compare(a, b) {
+  const [x, y] = [a, b].map((v) => v.split("-")[0].split(".").map(Number));
+  for (let i = 0; i < 3; i++) if ((x[i] || 0) !== (y[i] || 0)) return (x[i] || 0) - (y[i] || 0);
+  return 0;
+}
+
+// src/guide.js
 var GUIDE = `# Working in this VDS workspace
 
 This folder holds the product's requirements, flows and scenarios as plain files.
@@ -118,6 +128,15 @@ Read and write them with the vds command.
 4. Point flows at requirement ids. A state lists the ids it needs under \`requirements:\`.
 5. Run \`vds check\` before you finish. It prints "valid" when nothing is wrong; fix every problem it lists.
 `;
+var markerFor = (version) => `<!-- vds ${version} -->`;
+function guideText() {
+  return `${markerFor(VERSION)}
+${GUIDE}`;
+}
+
+// src/init.js
+var FOLDERS = ["capabilities", "flows", "scenarios"];
+var FIRST_PORT = 4600;
 async function freePort() {
   for (let port = FIRST_PORT; ; port++) {
     const free = await new Promise((resolve2) => {
@@ -136,12 +155,98 @@ async function init(root) {
   }
   const port = await freePort();
   for (const dir of FOLDERS) mkdirSync(join(root, dir), { recursive: true });
-  writeFileSync(join(root, "VDS.md"), GUIDE);
+  writeFileSync(join(root, "VDS.md"), guideText());
   writeFileSync(join(root, ".vds.json"), `${JSON.stringify({ port })}
 `);
   return 0;
 }
 
+// src/update.js
+import { spawnSync } from "node:child_process";
+import { existsSync as existsSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "node:fs";
+import { dirname, join as join2 } from "node:path";
+import { fileURLToPath } from "node:url";
+var REGISTRY = "https://registry.npmjs.org";
+var MARKER = /^<!-- vds (\d+\.\d+\.\d+\S*) -->/;
+async function newestVersion() {
+  const base = process.env.VDS_REGISTRY ?? REGISTRY;
+  try {
+    const res = await fetch(`${base}/@teurons%2fvds`);
+    if (!res.ok) throw new Error(`status ${res.status}`);
+    return (await res.json())["dist-tags"].latest;
+  } catch (e) {
+    throw new Error(`could not reach the npm registry: ${e.message}`);
+  }
+}
+function installKind() {
+  const file = fileURLToPath(import.meta.url);
+  if (file.includes("/_npx/")) return { kind: "npx" };
+  const at = file.indexOf("/node_modules/");
+  const root = at > 0 ? file.slice(0, at) : null;
+  if (root && existsSync2(join2(root, "package.json"))) return { kind: "project", root };
+  return { kind: "global" };
+}
+function installPlan(version) {
+  const spec = `@teurons/vds@${version}`;
+  const found = installKind();
+  if (found.kind === "project") {
+    const has = (f) => existsSync2(join2(found.root, f));
+    const cmd = has("pnpm-lock.yaml") ? `pnpm add -D ${spec}` : has("yarn.lock") ? `yarn add -D ${spec}` : `npm install -D ${spec}`;
+    return { ...found, cmd, bin: join2(found.root, "node_modules", ".bin", "vds") };
+  }
+  return { ...found, cmd: `npm install -g ${spec}`, bin: "vds" };
+}
+function refreshGuide(folder) {
+  const path = join2(folder, "VDS.md");
+  if (!existsSync2(path)) return false;
+  const current = readFileSync3(path, "utf8");
+  const marked = current.match(MARKER)?.[1];
+  if (marked && compare(marked, VERSION) >= 0) return false;
+  const next = guideText();
+  if (next === current) return false;
+  writeFileSync2(path, next);
+  return true;
+}
+function runShell(cmd, version, cwd) {
+  return spawnSync(cmd, {
+    shell: true,
+    stdio: "inherit",
+    cwd,
+    env: { ...process.env, VDS_TARGET_VERSION: version }
+  });
+}
+async function update(folder, { guideOnly = false } = {}) {
+  if (guideOnly) {
+    if (refreshGuide(folder)) console.log(`VDS.md rewritten for vds ${VERSION}`);
+    return 0;
+  }
+  const newest = await newestVersion();
+  if (compare(newest, VERSION) > 0) {
+    const plan = installPlan(newest);
+    if (plan.kind === "npx" && !process.env.VDS_INSTALL_CMD) {
+      console.log("npx already fetches the newest vds each run; use npx @teurons/vds@latest.");
+      return 0;
+    }
+    const cmd = process.env.VDS_INSTALL_CMD ?? plan.cmd;
+    if (runShell(cmd, newest, plan.root).status !== 0) {
+      console.error(`install failed: ${cmd}`);
+      return 1;
+    }
+    console.log(`vds updated from ${VERSION} to ${newest}`);
+    const bin = process.env.VDS_BIN ?? plan.bin;
+    const r = spawnSync(bin, ["update", "--guide-only", folder], { stdio: "inherit" });
+    if (r.status !== 0)
+      console.error(`could not refresh VDS.md with vds ${newest}; run vds update again`);
+    return 0;
+  }
+  if (refreshGuide(folder)) {
+    console.log(`vds ${VERSION} is the newest; VDS.md rewritten to match it`);
+    return 0;
+  }
+  console.log(`everything is current: vds ${VERSION} is the newest and ${folder} is up to date`);
+  return 0;
+}
+
 // src/bin.js
 var FOLDERS2 = ["capabilities", "flows", "scenarios"];
 function readWorkspace(root) {
@@ -149,16 +254,19 @@ function readWorkspace(root) {
   for (const dir of FOLDERS2) {
     let names = [];
     try {
-      names = readdirSync(join2(root, dir));
+      names = readdirSync(join3(root, dir));
     } catch {
       continue;
     }
-    for (const name of names) files[`${dir}/${name}`] = readFileSync2(join2(root, dir, name), "utf8");
+    for (const name of names) files[`${dir}/${name}`] = readFileSync4(join3(root, dir, name), "utf8");
   }
   return files;
 }
-async function main([command, folder = "."]) {
+async function main(argv) {
+  const guideOnly = argv.includes("--guide-only");
+  const [command, folder = "."] = argv.filter((a) => a !== "--guide-only");
   if (command === "init") return init(resolve(folder));
+  if (command === "update") return update(resolve(folder), { guideOnly });
   const mapper = await loadMapper();
   const files = readWorkspace(resolve(folder));
   if (command === "check") {
@@ -176,7 +284,14 @@ async function main([command, folder = "."]) {
     process.stdout.write(mapper.v2Index(files));
     return 0;
   }
-  console.error("usage: vds init [folder] | vds check [folder] | vds index [folder]");
+  console.error(
+    "usage: vds init [folder] | vds check [folder] | vds index [folder] | vds update [folder]"
+  );
   return 2;
 }
-process.exitCode = await main(process.argv.slice(2));
+try {
+  process.exitCode = await main(process.argv.slice(2));
+} catch (e) {
+  console.error(e.message);
+  process.exitCode = 1;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teurons/vds",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "The vds command: check, index and run a VDS workspace on your machine.",
   "type": "module",
   "bin": {
@@ -19,7 +19,6 @@
     "url": "git+https://github.com/teurons/vds.git"
   },
   "publishConfig": {
-    "access": "public",
-    "tag": "next"
+    "access": "public"
   }
 }