@teurons/vds 0.0.0-stage → 0.0.2

package/README.md

@@ -1,3 +1,52 @@
-# Temporary Holding Version
+# @teurons/vds
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+## Set it up with your AI agent
+
+Copy this prompt into Claude Code, Codex or any coding agent, run from the root of your project:
+
+```text
+Set up VDS in this project.
+
+1. Run `npx -y @teurons/vds@next 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
+   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.
+4. Add a short section to this project's AGENTS.md (or CLAUDE.md if that is
+   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.
+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
+```
+
+`folder` defaults to the current folder.
+
+## A workspace
+
+```text
+vds-workspace/
+  VDS.md                      how agents and people work on this spec
+  .vds.json                   local settings, such as the studio port
+  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
+```
+
+Needs Node 20 or later.

package/dist/vds.js

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+
+// src/bin.js
+import { readdirSync, readFileSync as readFileSync2 } from "node:fs";
+import { join as join2, resolve } from "node:path";
+
+// ../../specs/js/load.js
+import { readFileSync } from "node:fs";
+var compiled = /* @__PURE__ */ new Map();
+function compile(url, build) {
+  const key = String(url);
+  if (!compiled.has(key)) {
+    let bytes;
+    try {
+      bytes = readFileSync(url);
+    } catch {
+      throw new Error(`${key.split("/").pop()} is missing. Build it with: ${build}`);
+    }
+    compiled.set(key, new WebAssembly.Module(bytes));
+  }
+  return compiled.get(key);
+}
+
+// ../../specs/js/bridge.js
+var enc = new TextEncoder();
+var dec = new TextDecoder();
+function instanceOf(module) {
+  return new WebAssembly.Instance(module, {});
+}
+function bridge(instance) {
+  const x = instance.exports;
+  const read = (packed) => {
+    const ptr = Number(packed >> 32n);
+    const len = Number(packed & 0xffffffffn);
+    const text = dec.decode(new Uint8Array(x.memory.buffer, ptr, len));
+    x.dealloc(ptr, len);
+    return text;
+  };
+  const call = (fn, input) => {
+    const bytes = enc.encode(input);
+    const ptr = x.alloc(bytes.length);
+    new Uint8Array(x.memory.buffer, ptr, bytes.length).set(bytes);
+    return read(x[fn](ptr, bytes.length));
+  };
+  return {
+    call,
+    /** Calls an export with a value as JSON and returns its answer parsed. */
+    json: (fn, input) => JSON.parse(call(fn, JSON.stringify(input))),
+    /** Calls an export that takes nothing and returns its answer parsed. */
+    none: (fn) => JSON.parse(read(x[fn]()))
+  };
+}
+
+// ../../mapper/js/index.js
+function bind(instance) {
+  const { call, json } = bridge(instance);
+  return {
+    validate: (files) => json("validate", files),
+    v2Check: (files) => json("v2_check", files),
+    v2Index: (files) => call("v2_index", JSON.stringify(files)),
+    load: (files) => json("load", files),
+    check: (changes) => json("check", changes),
+    apply: (changes) => json("apply", changes),
+    toYaml: (doc) => call("to_yaml", typeof doc === "string" ? doc : JSON.stringify(doc)),
+    toYamlOver: (original, doc) => call("to_yaml_over", JSON.stringify({ original, doc })),
+    parseYaml: (text) => {
+      const r = JSON.parse(call("parse_yaml", text));
+      if ("error" in r) throw new Error(r.error);
+      return r.ok;
+    },
+    nextId: (kind, parent) => json("next_id", { kind, parent: parent ?? null }).id ?? null,
+    readSettings: (text) => json("read_settings", { settings: text ?? null }),
+    workspaceFiles: (paths) => json("workspace_files", paths),
+    classify: (files) => json("classify", files),
+    pathOf: (input) => json("path_of", input).path,
+    describe: (settings, path) => json("path_of", { settings: settings ?? null, of: "describe", path }),
+    parseFeature: (text) => JSON.parse(call("parse_feature", text)),
+    writeFeature: (input) => call("write_feature", JSON.stringify(input)),
+    retitleFeature: (text, requirement, title) => call("retitle_feature", JSON.stringify({ text, requirement, title })),
+    putScenario: (text, scenario) => call("put_scenario", JSON.stringify({ text, scenario })),
+    removeScenario: (text, id) => call("remove_scenario", JSON.stringify({ text, id }))
+  };
+}
+function instantiate(module) {
+  return bind(instanceOf(module));
+}
+
+// ../../mapper/js/node.js
+function mapperModule() {
+  return compile(new URL("./vds_mapper.wasm", import.meta.url), "pnpm --filter @vds/mapper build");
+}
+function loadMapper() {
+  return instantiate(mapperModule());
+}
+
+// src/init.js
+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;
+var GUIDE = `# Working in this VDS workspace
+
+This folder holds the product's requirements, flows and scenarios as plain files.
+Read and write them with the vds command.
+
+## Layout
+
+- capabilities/<CODE>.yaml: one capability and its requirements (ids like ONB-01).
+- flows/<id>.yaml: a journey made of states; each state points at requirement ids.
+- scenarios/<REQ-ID>.feature: Given, When, Then scenarios for one requirement.
+
+## How to work
+
+1. Run \`vds index\` first. It prints one line per flow and requirement, so you know what exists.
+2. Open one file at a time. Read only the file you are changing.
+3. Write requirements in EARS: "When <trigger>, the system SHALL <response>." The system is always the subject.
+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.
+`;
+async function freePort() {
+  for (let port = FIRST_PORT; ; port++) {
+    const free = await new Promise((resolve2) => {
+      const server = createServer();
+      server.once("error", () => resolve2(false));
+      server.listen(port, () => server.close(() => resolve2(true)));
+    });
+    if (free) return port;
+  }
+}
+async function init(root) {
+  const found = [...FOLDERS, "VDS.md"].filter((name) => existsSync(join(root, name)));
+  if (found.length > 0) {
+    console.error(`nothing changed; this folder already has: ${found.join(", ")}`);
+    return 1;
+  }
+  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.json"), `${JSON.stringify({ port })}
+`);
+  return 0;
+}
+
+// src/bin.js
+var FOLDERS2 = ["capabilities", "flows", "scenarios"];
+function readWorkspace(root) {
+  const files = {};
+  for (const dir of FOLDERS2) {
+    let names = [];
+    try {
+      names = readdirSync(join2(root, dir));
+    } catch {
+      continue;
+    }
+    for (const name of names) files[`${dir}/${name}`] = readFileSync2(join2(root, dir, name), "utf8");
+  }
+  return files;
+}
+async function main([command, folder = "."]) {
+  if (command === "init") return init(resolve(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;
+  }
+  if (command === "index") {
+    process.stdout.write(mapper.v2Index(files));
+    return 0;
+  }
+  console.error("usage: vds init [folder] | vds check [folder] | vds index [folder]");
+  return 2;
+}
+process.exitCode = await main(process.argv.slice(2));

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "@teurons/vds",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2",
+  "description": "The vds command: check, index and run a VDS workspace on your machine.",
+  "type": "module",
+  "bin": {
+    "vds": "dist/vds.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {},
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/teurons/vds.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  }
+}