@rness/cli 0.2.0 → 0.4.0

package/README.md

@@ -1,11 +1,12 @@
 # @rness/cli
 
 The `rness` command: configuration-plane CLI for rness workspaces. It
-resolves, validates and (from 0.3.0) syncs an organisation's context for AI
-coding agents. Not an agent — no LLM loop.
+resolves, validates and syncs an organisation's context for AI coding agents.
+Not an agent — no LLM loop.
 
 ## Install
 
+    npm create rness <org>     # start a workspace for github.com/<org>, or join its .rness
     npm i -g @rness/cli        # the command is `rness`
     npx @rness/cli --help
 
@@ -14,11 +15,41 @@ Inside a workspace, every `rness` delegates to the copy pinned in
 
 ## Commands
 
-    rness context [--scope <name>] [--json]   Resolve the context for a scope
-    rness validate                            Check .rness/ against the contract
+    rness create <org> [--dir <path>] [--repos a,b] [--pm npm|pnpm|yarn|bun] [--ssh] [--skip-install] -y
+    rness add <repo> [--scopes apps/web,packages/ui] [--ssh] -y
+    rness sync [--scope <name>] [--check] [--pull] -y
+    rness context [--scope <name>] [--json]
+    rness validate
 
-Exit codes: 0 success, 1 handled error, 2 bad usage. `RNESS_DEBUG=1` adds
-stack traces; `RNESS_NO_DELEGATE=1` skips the delegation.
+`create` never runs inside a workspace. `add`, `sync` and `create` ask for
+confirmation in a terminal; pass `-y`/`--yes` in scripts. `sync --check`
+writes nothing and exits 1 when a block is out of date — use it in CI.
+
+Exit codes: 0 success, 1 failure, 2 usage — or a refusal without a TTY.
+`RNESS_DEBUG=1` adds stack traces; `RNESS_NO_DELEGATE=1` skips the delegation.
+
+## 0.4.0 — create, add, the shims
+
+- `npm create rness <org>` starts a new workspace for `github.com/<org>` or
+  joins its existing `.rness`.
+- `rness add <repo>` clones (or adopts) a repository under `org/`, declares
+  it and any `--scopes` sub-directories, then syncs.
+- `create-rness` and `@rness/create` are two-file shims pinned to the exact
+  same version as `@rness/cli`, so the short `npm create` commands run this
+  CLI.
+- A new workspace's scaffold ships a `pnpm-workspace.yaml`
+  (`minimumReleaseAgeExclude: ['@rness/cli']`) — pnpm 12 otherwise refuses a
+  version published less than 24h earlier.
+
+## 0.3.0 — what changed for a 0.2.0 workspace
+
+- The directory decides a file's scope. `scopes: […]` and `scope: global`
+  front-matter keys no longer route anything; `rness validate` reports them.
+  Move the file instead (`standards/<scope>/…` or the collection root).
+- `rness.json` may declare `"org": "<github-org>"`; without it the
+  workspace directory name is used and `validate` warns.
+- `validate` now checks every generated block: a stale block is an error,
+  a missing one a warning — run `rness sync`.
 
 ## Develop
 

package/dist/bin/rness.js

@@ -1,38 +1,14 @@
 #!/usr/bin/env node
 import {
   VERSION,
-  findWorkspace,
+  findDelegate,
   reportError,
   run
-} from "../chunk-6ASX7VBO.js";
+} from "../chunk-IW5IHSPC.js";
 
 // src/bin/rness.ts
 import { pathToFileURL } from "url";
 
-// src/core/delegate.ts
-import { readFile } from "fs/promises";
-import { join } from "path";
-async function findDelegate(cwd, ownVersion) {
-  let root;
-  let rnessDir;
-  try {
-    const ws = await findWorkspace(cwd);
-    root = ws.root;
-    rnessDir = ws.rnessDir;
-  } catch {
-    return null;
-  }
-  const pkgDir = join(rnessDir, "node_modules", "@rness", "cli");
-  let version;
-  try {
-    version = JSON.parse(await readFile(join(pkgDir, "package.json"), "utf8")).version;
-  } catch {
-    return null;
-  }
-  if (typeof version !== "string" || version === ownVersion) return null;
-  return { entry: join(pkgDir, "dist", "index.js"), version, root };
-}
-
 // src/core/node-version.ts
 var MIN_NODE_MAJOR = 24;
 function nodeMajor(version) {
@@ -50,22 +26,33 @@ process.stdout.on("error", (e) => {
 });
 async function main() {
   if (!isSupportedNode(process.versions.node)) {
-    process.stderr.write(`rness needs Node ${MIN_NODE_MAJOR} or newer (running ${process.version})
-`);
+    process.stderr.write(
+      `rness needs Node ${MIN_NODE_MAJOR} or newer (running ${process.version})
+`
+    );
     return 1;
   }
   const argv = process.argv.slice(2);
   const skipDelegation = argv[0] === "create" || process.env["RNESS_NO_DELEGATE"] === "1";
   const delegate = skipDelegation ? null : await findDelegate(process.cwd(), VERSION);
   if (delegate !== null) {
-    const broken = (reason) => new Error(`@rness/cli ${delegate.version} pinned in ${delegate.root}/.rness is not installed correctly (${reason}); reinstall in .rness/`);
+    const broken = (reason) => new Error(
+      `@rness/cli ${delegate.version} pinned in ${delegate.root}/.rness is not installed correctly (${reason}); reinstall in .rness/`
+    );
+    if (process.env["RNESS_DEBUG"] === "1") {
+      process.stderr.write(
+        `rness: delegating to @rness/cli ${delegate.version} (${delegate.entry})
+`
+      );
+    }
     let mod;
     try {
       mod = await import(pathToFileURL(delegate.entry).href);
     } catch (e) {
       throw broken(e instanceof Error ? e.message : String(e));
     }
-    if (typeof mod["run"] !== "function") throw broken("dist/index.js does not export run");
+    if (typeof mod["run"] !== "function")
+      throw broken("dist/index.js does not export run");
     const delegateRun = mod["run"];
     const code = await delegateRun(argv);
     return typeof code === "number" ? code : 1;

package/dist/bin/rness.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/bin/rness.ts","../../src/core/delegate.ts","../../src/core/node-version.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { pathToFileURL } from 'node:url'\nimport { run } from '../cli.ts'\nimport { VERSION } from '../version.ts'\nimport { findDelegate } from '../core/delegate.ts'\nimport { isSupportedNode, MIN_NODE_MAJOR } from '../core/node-version.ts'\nimport { reportError } from '../report.ts'\n\n// `rness context | head`: once the reader has its lines it closes the pipe and\n// every further write emits EPIPE on stdout. Nothing is left to deliver, so end\n// quietly with success. This is the one process.exit() in the code base — it\n// runs only when there is no output left to drain (see main() below).\nprocess.stdout.on('error', (e: NodeJS.ErrnoException) => {\n  if (e.code === 'EPIPE') process.exit(0)\n  throw e\n})\n\n// Set process.exitCode rather than calling process.exit(): process.exit()\n// terminates before Node drains an async stdout pipe, truncating piped output\n// at the ~64 KiB pipe buffer (breaks `rness context --json | jq`, `$(...)`).\nasync function main(): Promise<number> {\n  if (!isSupportedNode(process.versions.node)) {\n    process.stderr.write(`rness needs Node ${MIN_NODE_MAJOR} or newer (running ${process.version})\\n`)\n    return 1\n  }\n  const argv = process.argv.slice(2)\n  const skipDelegation = argv[0] === 'create' || process.env['RNESS_NO_DELEGATE'] === '1'\n  const delegate = skipDelegation ? null : await findDelegate(process.cwd(), VERSION)\n  if (delegate !== null) {\n    const broken = (reason: string): Error =>\n      new Error(`@rness/cli ${delegate.version} pinned in ${delegate.root}/.rness is not installed correctly (${reason}); reinstall in .rness/`)\n    let mod: Record<string, unknown>\n    try {\n      mod = (await import(pathToFileURL(delegate.entry).href)) as Record<string, unknown>\n    } catch (e) {\n      throw broken(e instanceof Error ? e.message : String(e))\n    }\n    if (typeof mod['run'] !== 'function') throw broken('dist/index.js does not export run')\n    const delegateRun = mod['run'] as (argv: string[]) => Promise<unknown>\n    const code = await delegateRun(argv)\n    return typeof code === 'number' ? code : 1\n  }\n  return run(argv)\n}\n\nmain()\n  .then((code) => {\n    process.exitCode = code\n  })\n  .catch((e: unknown) => {\n    process.exitCode = reportError(e)\n  })\n","import { readFile } from 'node:fs/promises'\nimport { join } from 'node:path'\nimport { findWorkspace } from './workspace.ts'\n\nexport interface Delegate {\n  /** Absolute path of the pinned copy's `dist/index.js`. */\n  entry: string\n  version: string\n  /** Workspace root (the directory holding `.rness/`). */\n  root: string\n}\n\n/**\n * The `@rness/cli` pinned in `<workspace>/.rness/package.json` (installed under\n * `.rness/node_modules`), when it exists and is not the running version. The\n * pinned copy is the only one that should ever act on a workspace.\n */\nexport async function findDelegate(cwd: string, ownVersion: string): Promise<Delegate | null> {\n  let root: string\n  let rnessDir: string\n  try {\n    const ws = await findWorkspace(cwd)\n    root = ws.root\n    rnessDir = ws.rnessDir\n  } catch {\n    return null\n  }\n  const pkgDir = join(rnessDir, 'node_modules', '@rness', 'cli')\n  let version: unknown\n  try {\n    version = (JSON.parse(await readFile(join(pkgDir, 'package.json'), 'utf8')) as { version?: unknown }).version\n  } catch {\n    return null\n  }\n  if (typeof version !== 'string' || version === ownVersion) return null\n  return { entry: join(pkgDir, 'dist', 'index.js'), version, root }\n}\n","export const MIN_NODE_MAJOR = 24\n\nexport function nodeMajor(version: string): number {\n  const major = Number.parseInt(version.split('.')[0] ?? '', 10)\n  return Number.isNaN(major) ? 0 : major\n}\n\nexport function isSupportedNode(version: string): boolean {\n  return nodeMajor(version) >= MIN_NODE_MAJOR\n}\n"],"mappings":";;;;;;;;;AACA,SAAS,qBAAqB;;;ACD9B,SAAS,gBAAgB;AACzB,SAAS,YAAY;AAgBrB,eAAsB,aAAa,KAAa,YAA8C;AAC5F,MAAI;AACJ,MAAI;AACJ,MAAI;AACF,UAAM,KAAK,MAAM,cAAc,GAAG;AAClC,WAAO,GAAG;AACV,eAAW,GAAG;AAAA,EAChB,QAAQ;AACN,WAAO;AAAA,EACT;AACA,QAAM,SAAS,KAAK,UAAU,gBAAgB,UAAU,KAAK;AAC7D,MAAI;AACJ,MAAI;AACF,cAAW,KAAK,MAAM,MAAM,SAAS,KAAK,QAAQ,cAAc,GAAG,MAAM,CAAC,EAA4B;AAAA,EACxG,QAAQ;AACN,WAAO;AAAA,EACT;AACA,MAAI,OAAO,YAAY,YAAY,YAAY,WAAY,QAAO;AAClE,SAAO,EAAE,OAAO,KAAK,QAAQ,QAAQ,UAAU,GAAG,SAAS,KAAK;AAClE;;;ACpCO,IAAM,iBAAiB;AAEvB,SAAS,UAAU,SAAyB;AACjD,QAAM,QAAQ,OAAO,SAAS,QAAQ,MAAM,GAAG,EAAE,CAAC,KAAK,IAAI,EAAE;AAC7D,SAAO,OAAO,MAAM,KAAK,IAAI,IAAI;AACnC;AAEO,SAAS,gBAAgB,SAA0B;AACxD,SAAO,UAAU,OAAO,KAAK;AAC/B;;;AFGA,QAAQ,OAAO,GAAG,SAAS,CAAC,MAA6B;AACvD,MAAI,EAAE,SAAS,QAAS,SAAQ,KAAK,CAAC;AACtC,QAAM;AACR,CAAC;AAKD,eAAe,OAAwB;AACrC,MAAI,CAAC,gBAAgB,QAAQ,SAAS,IAAI,GAAG;AAC3C,YAAQ,OAAO,MAAM,oBAAoB,cAAc,sBAAsB,QAAQ,OAAO;AAAA,CAAK;AACjG,WAAO;AAAA,EACT;AACA,QAAM,OAAO,QAAQ,KAAK,MAAM,CAAC;AACjC,QAAM,iBAAiB,KAAK,CAAC,MAAM,YAAY,QAAQ,IAAI,mBAAmB,MAAM;AACpF,QAAM,WAAW,iBAAiB,OAAO,MAAM,aAAa,QAAQ,IAAI,GAAG,OAAO;AAClF,MAAI,aAAa,MAAM;AACrB,UAAM,SAAS,CAAC,WACd,IAAI,MAAM,cAAc,SAAS,OAAO,cAAc,SAAS,IAAI,uCAAuC,MAAM,yBAAyB;AAC3I,QAAI;AACJ,QAAI;AACF,YAAO,MAAM,OAAO,cAAc,SAAS,KAAK,EAAE;AAAA,IACpD,SAAS,GAAG;AACV,YAAM,OAAO,aAAa,QAAQ,EAAE,UAAU,OAAO,CAAC,CAAC;AAAA,IACzD;AACA,QAAI,OAAO,IAAI,KAAK,MAAM,WAAY,OAAM,OAAO,mCAAmC;AACtF,UAAM,cAAc,IAAI,KAAK;AAC7B,UAAM,OAAO,MAAM,YAAY,IAAI;AACnC,WAAO,OAAO,SAAS,WAAW,OAAO;AAAA,EAC3C;AACA,SAAO,IAAI,IAAI;AACjB;AAEA,KAAK,EACF,KAAK,CAAC,SAAS;AACd,UAAQ,WAAW;AACrB,CAAC,EACA,MAAM,CAAC,MAAe;AACrB,UAAQ,WAAW,YAAY,CAAC;AAClC,CAAC;","names":[]}
+{"version":3,"sources":["../../src/bin/rness.ts","../../src/core/node-version.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { pathToFileURL } from 'node:url'\n\nimport { run } from '../cli.ts'\nimport { findDelegate } from '../core/delegate.ts'\nimport { MIN_NODE_MAJOR, isSupportedNode } from '../core/node-version.ts'\nimport { reportError } from '../report.ts'\nimport { VERSION } from '../version.ts'\n\n// `rness context | head`: once the reader has its lines it closes the pipe and\n// every further write emits EPIPE on stdout. Nothing is left to deliver, so end\n// quietly with success. This is the one process.exit() in the code base — it\n// runs only when there is no output left to drain (see main() below).\nprocess.stdout.on('error', (e: NodeJS.ErrnoException) => {\n  if (e.code === 'EPIPE') process.exit(0)\n  throw e\n})\n\n// Set process.exitCode rather than calling process.exit(): process.exit()\n// terminates before Node drains an async stdout pipe, truncating piped output\n// at the ~64 KiB pipe buffer (breaks `rness context --json | jq`, `$(...)`).\nasync function main(): Promise<number> {\n  if (!isSupportedNode(process.versions.node)) {\n    process.stderr.write(\n      `rness needs Node ${MIN_NODE_MAJOR} or newer (running ${process.version})\\n`\n    )\n    return 1\n  }\n  const argv = process.argv.slice(2)\n  const skipDelegation =\n    argv[0] === 'create' || process.env['RNESS_NO_DELEGATE'] === '1'\n  const delegate = skipDelegation\n    ? null\n    : await findDelegate(process.cwd(), VERSION)\n  if (delegate !== null) {\n    const broken = (reason: string): Error =>\n      new Error(\n        `@rness/cli ${delegate.version} pinned in ${delegate.root}/.rness is not installed correctly (${reason}); reinstall in .rness/`\n      )\n    if (process.env['RNESS_DEBUG'] === '1') {\n      process.stderr.write(\n        `rness: delegating to @rness/cli ${delegate.version} (${delegate.entry})\\n`\n      )\n    }\n    let mod: Record<string, unknown>\n    try {\n      mod = (await import(pathToFileURL(delegate.entry).href)) as Record<\n        string,\n        unknown\n      >\n    } catch (e) {\n      throw broken(e instanceof Error ? e.message : String(e))\n    }\n    if (typeof mod['run'] !== 'function')\n      throw broken('dist/index.js does not export run')\n    const delegateRun = mod['run'] as (argv: string[]) => Promise<unknown>\n    const code = await delegateRun(argv)\n    return typeof code === 'number' ? code : 1\n  }\n  return run(argv)\n}\n\nmain()\n  .then((code) => {\n    process.exitCode = code\n  })\n  .catch((e: unknown) => {\n    process.exitCode = reportError(e)\n  })\n","export const MIN_NODE_MAJOR = 24\n\nexport function nodeMajor(version: string): number {\n  const major = Number.parseInt(version.split('.')[0] ?? '', 10)\n  return Number.isNaN(major) ? 0 : major\n}\n\nexport function isSupportedNode(version: string): boolean {\n  return nodeMajor(version) >= MIN_NODE_MAJOR\n}\n"],"mappings":";;;;;;;;;AACA,SAAS,qBAAqB;;;ACDvB,IAAM,iBAAiB;AAEvB,SAAS,UAAU,SAAyB;AACjD,QAAM,QAAQ,OAAO,SAAS,QAAQ,MAAM,GAAG,EAAE,CAAC,KAAK,IAAI,EAAE;AAC7D,SAAO,OAAO,MAAM,KAAK,IAAI,IAAI;AACnC;AAEO,SAAS,gBAAgB,SAA0B;AACxD,SAAO,UAAU,OAAO,KAAK;AAC/B;;;ADIA,QAAQ,OAAO,GAAG,SAAS,CAAC,MAA6B;AACvD,MAAI,EAAE,SAAS,QAAS,SAAQ,KAAK,CAAC;AACtC,QAAM;AACR,CAAC;AAKD,eAAe,OAAwB;AACrC,MAAI,CAAC,gBAAgB,QAAQ,SAAS,IAAI,GAAG;AAC3C,YAAQ,OAAO;AAAA,MACb,oBAAoB,cAAc,sBAAsB,QAAQ,OAAO;AAAA;AAAA,IACzE;AACA,WAAO;AAAA,EACT;AACA,QAAM,OAAO,QAAQ,KAAK,MAAM,CAAC;AACjC,QAAM,iBACJ,KAAK,CAAC,MAAM,YAAY,QAAQ,IAAI,mBAAmB,MAAM;AAC/D,QAAM,WAAW,iBACb,OACA,MAAM,aAAa,QAAQ,IAAI,GAAG,OAAO;AAC7C,MAAI,aAAa,MAAM;AACrB,UAAM,SAAS,CAAC,WACd,IAAI;AAAA,MACF,cAAc,SAAS,OAAO,cAAc,SAAS,IAAI,uCAAuC,MAAM;AAAA,IACxG;AACF,QAAI,QAAQ,IAAI,aAAa,MAAM,KAAK;AACtC,cAAQ,OAAO;AAAA,QACb,mCAAmC,SAAS,OAAO,KAAK,SAAS,KAAK;AAAA;AAAA,MACxE;AAAA,IACF;AACA,QAAI;AACJ,QAAI;AACF,YAAO,MAAM,OAAO,cAAc,SAAS,KAAK,EAAE;AAAA,IAIpD,SAAS,GAAG;AACV,YAAM,OAAO,aAAa,QAAQ,EAAE,UAAU,OAAO,CAAC,CAAC;AAAA,IACzD;AACA,QAAI,OAAO,IAAI,KAAK,MAAM;AACxB,YAAM,OAAO,mCAAmC;AAClD,UAAM,cAAc,IAAI,KAAK;AAC7B,UAAM,OAAO,MAAM,YAAY,IAAI;AACnC,WAAO,OAAO,SAAS,WAAW,OAAO;AAAA,EAC3C;AACA,SAAO,IAAI,IAAI;AACjB;AAEA,KAAK,EACF,KAAK,CAAC,SAAS;AACd,UAAQ,WAAW;AACrB,CAAC,EACA,MAAM,CAAC,MAAe;AACrB,UAAQ,WAAW,YAAY,CAAC;AAClC,CAAC;","names":[]}