@teurons/vds 0.0.1 → 0.0.3

package/README.md

@@ -0,0 +1,52 @@
+# @teurons/vds
+
+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.
+
+## 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 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 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 check vds-workspace` and confirm it prints valid.
+6. Tell me what you created and changed, file by file.
+```
+
+## Commands
+
+```sh
+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
+```
+
+`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

@@ -2,7 +2,7 @@
 
 // src/bin.js
 import { readdirSync, readFileSync as readFileSync2 } from "node:fs";
-import { join, resolve } from "node:path";
+import { join as join2, resolve } from "node:path";
 
 // ../../specs/js/load.js
 import { readFileSync } from "node:fs";
@@ -93,22 +93,72 @@ function loadMapper() {
   return instantiate(mapperModule());
 }
 
-// src/bin.js
+// 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 FOLDERS) {
+  for (const dir of FOLDERS2) {
     let names = [];
     try {
-      names = readdirSync(join(root, dir));
+      names = readdirSync(join2(root, dir));
     } catch {
       continue;
     }
-    for (const name of names) files[`${dir}/${name}`] = readFileSync2(join(root, dir, name), "utf8");
+    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") {
@@ -126,7 +176,7 @@ async function main([command, folder = "."]) {
     process.stdout.write(mapper.v2Index(files));
     return 0;
   }
-  console.error("usage: vds check [folder] | vds index [folder]");
+  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,6 @@
 {
   "name": "@teurons/vds",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "The vds command: check, index and run a VDS workspace on your machine.",
   "type": "module",
   "bin": {
@@ -12,25 +12,13 @@
   "engines": {
     "node": ">=20"
   },
-  "scripts": {
-    "build": "node build.mjs",
-    "test": "vitest run",
-    "prepack": "node build.mjs",
-    "release": "node release.mjs"
-  },
   "dependencies": {},
-  "devDependencies": {
-    "@vds/mapper": "workspace:*",
-    "esbuild": "0.28.1",
-    "vitest": "5.0.1"
-  },
   "license": "UNLICENSED",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/teurons/vds.git"
   },
   "publishConfig": {
-    "access": "public",
-    "tag": "next"
+    "access": "public"
   }
 }