@teurons/vds 0.0.3 → 0.0.5

package/README.md

@@ -34,16 +34,18 @@ Set up VDS in this project.
 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.
+`folder` defaults to the current folder, or to `vds-workspace` inside it when the current folder
+is not a workspace itself. So from your project root, `vds check` checks `vds-workspace`.
 
 ## A workspace
 
 ```text
 vds-workspace/
   VDS.md                      how agents and people work on this spec
-  .vds.json                   local settings, such as the studio port
+  .vds.json                   local settings: the port the local studio will use (coming soon)
   capabilities/<CODE>.yaml    rules, each one EARS statement with an id like ONB-01
   flows/<id>.yaml             versioned flows whose steps point at rule ids
   scenarios/<RULE-ID>.feature Gherkin scenarios, one file per rule

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 { existsSync as existsSync3, 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.5";
+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,34 +254,50 @@ 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 = "."]) {
-  if (command === "init") return init(resolve(folder));
+function defaultFolder() {
+  const isWorkspace = [...FOLDERS2, "VDS.md"].some((name) => existsSync3(name));
+  return !isWorkspace && existsSync3("vds-workspace") ? "vds-workspace" : ".";
+}
+async function check(folder) {
   const mapper = await loadMapper();
-  const files = readWorkspace(resolve(folder));
-  if (command === "check") {
-    const findings = mapper.v2Check(files);
-    if ("error" in findings) throw new Error(findings.error);
-    if (findings.length === 0) {
-      console.log("valid");
-      return 0;
-    }
-    console.error(`${findings.length} problem(s):`);
-    for (const f of findings) console.error(`- ${f.path}: ${f.message} [${f.code}]`);
-    return 1;
+  const findings = mapper.v2Check(readWorkspace(resolve(folder)));
+  if ("error" in findings) throw new Error(findings.error);
+  if (findings.length === 0) {
+    console.log("valid");
+    return 0;
   }
+  console.error(`${findings.length} problem(s):`);
+  for (const f of findings) console.error(`- ${f.path}: ${f.message} [${f.code}]`);
+  return 1;
+}
+async function main(argv) {
+  const guideOnly = argv.includes("--guide-only");
+  const [command, named] = argv.filter((a) => a !== "--guide-only");
+  if (command === "init") return init(resolve(named ?? "."));
+  const folder = named ?? defaultFolder();
+  if (command === "update") return update(resolve(folder), { guideOnly });
+  if (command === "check") return check(folder);
   if (command === "index") {
-    process.stdout.write(mapper.v2Index(files));
+    const mapper = await loadMapper();
+    process.stdout.write(mapper.v2Index(readWorkspace(resolve(folder))));
     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.3",
+  "version": "0.0.5",
   "description": "The vds command: check, index and run a VDS workspace on your machine.",
   "type": "module",
   "bin": {