@nekostack/cli 1.0.0

package/dist/loaders/walk-workspace.js

@@ -0,0 +1,133 @@
+/**
+ * `walkWorkspace({ root, pattern? })` — discover `*.schema.{ts,js}`
+ * files under a workspace root and load each one into a
+ * `RegistrySourceEntry`. v0.7 Step 23.
+ *
+ * The CLI is the only filesystem walker (Master plan / CLI plan
+ * Decision #2). This function:
+ *
+ *   1. Glob-walks `pattern` (default `**​/*.schema.{ts,js}`) under
+ *      `root` using Node's built-in `fs/promises.glob` (Node 22+).
+ *      No external glob dep.
+ *   2. Reads each match's UTF-8 source text.
+ *   3. Hands the absolute path to `loadSchemaModule` from
+ *      `tsx-loader.ts`.
+ *   4. Builds one `RegistrySourceEntry` per successfully loaded module.
+ *   5. Collects every per-file failure into a separate `failures`
+ *      array — never short-circuits. The CLI dispatch layer (Steps
+ *      25+) decides whether to surface them and what exit code to
+ *      pick; this loader is silent.
+ *
+ * No `console.*`, no `process.exit`, no stderr / stdout writes —
+ * static-scan asserted by [`../../tests/loaders/walk-workspace.test.ts`](../../tests/loaders/walk-workspace.test.ts).
+ *
+ * This module does NOT:
+ *   - Build a `Registry` (that's `buildRegistry` on the schema side).
+ *   - Call any schema-side handler (`listHandler` etc. — Steps 29+).
+ *   - Format output (Steps 27 / 28).
+ *   - Decide exit codes (Step 25 dispatch + Step 26 exit-codes enum).
+ *
+ * Pattern semantics: a caller-supplied `pattern` **replaces** the
+ * default — it does not extend it. The CLI surface (Master plan CLI
+ * companion §"Locked subcommand surface") spells this out for the
+ * `[pattern]` positional on `generate` / `check`.
+ *
+ * Deterministic ordering: discovered paths are sorted ascending by
+ * their workspace-relative form (forward-slash-normalized) before
+ * loading. Downstream sort by `schemaId` is still required for
+ * registry order (the listHandler does that); this sort is purely so
+ * walk-time errors and CLI output have a stable order across runs.
+ */
+import { readFile } from "node:fs/promises";
+import { glob } from "node:fs/promises";
+import { isAbsolute, resolve, sep } from "node:path";
+import { loadSchemaModule } from "./tsx-loader.js";
+// =============================================================================
+// Public types
+// =============================================================================
+export const DEFAULT_SCHEMA_PATTERN = "**/*.schema.{ts,js}";
+// =============================================================================
+// Walker
+// =============================================================================
+export async function walkWorkspace(opts) {
+    const pattern = opts.pattern ?? DEFAULT_SCHEMA_PATTERN;
+    const rootAbs = isAbsolute(opts.root) ? opts.root : resolve(opts.root);
+    // Glob walk. `cwd` keeps relative output in sync with `rootAbs` so
+    // we can compute both forms cheaply below.
+    let relativePaths;
+    try {
+        relativePaths = await collectGlob(pattern, rootAbs);
+    }
+    catch (cause) {
+        return {
+            entries: [],
+            failures: [
+                {
+                    path: rootAbs,
+                    reason: "io_error",
+                    message: errorMessageOf(cause),
+                    cause,
+                },
+            ],
+        };
+    }
+    // Deterministic ordering: alphabetical on forward-slash-normalized
+    // relative paths. Stable across Windows/POSIX and stable across runs.
+    const normalized = relativePaths
+        .map((p) => p.split(sep).join("/"))
+        .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    const entries = [];
+    const failures = [];
+    for (const rel of normalized) {
+        const abs = resolve(rootAbs, rel);
+        let sourceText;
+        try {
+            sourceText = await readFile(abs, "utf8");
+        }
+        catch (cause) {
+            failures.push({
+                path: rel,
+                reason: "io_error",
+                message: errorMessageOf(cause),
+                cause,
+            });
+            continue;
+        }
+        const r = await loadSchemaModule(abs);
+        if (!r.success) {
+            // Re-key the failure path to the workspace-relative form so
+            // downstream output is consistent with `sourcePath` on the
+            // successful entries.
+            failures.push({ ...r.failure, path: rel });
+            continue;
+        }
+        entries.push({
+            sourcePath: rel,
+            sourceText,
+            schemas: r.data.schemas,
+        });
+    }
+    return { entries, failures };
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+async function collectGlob(pattern, cwd) {
+    const out = [];
+    for await (const p of glob(pattern, { cwd }))
+        out.push(p);
+    return out;
+}
+function errorMessageOf(err) {
+    if (err instanceof Error)
+        return err.message;
+    if (typeof err === "string")
+        return err;
+    try {
+        return JSON.stringify(err);
+    }
+    catch {
+        return String(err);
+    }
+}
+//# sourceMappingURL=walk-workspace.js.map

package/dist/loaders/walk-workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk-workspace.js","sourceRoot":"","sources":["../../src/loaders/walk-workspace.ts"],"names":[],"mappings":"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"}

package/docs/SCOPE.md

@@ -0,0 +1,42 @@
+# @nekostack/cli — Scope & Invariants
+
+## What this package is
+
+The `neko` CLI binary. Installed via `npm install -g @nekostack/cli` or `npx neko`. Dispatches schema commands through `@nekostack/schema`. Commander-based, fully testable in-process.
+
+## Commands (v1.0)
+
+| Command | Description |
+|---|---|
+| `neko schema list [globs]` | Discover schema files |
+| `neko schema diff [globs]` | Diff against stored snapshots |
+| `neko schema check [globs]` | Validate against schema contract rules |
+| `neko schema generate [globs]` | Generate Zod / TS / JSON Schema / OpenAPI |
+| `neko schema migrate list` | List available migration files |
+| `neko schema migrate plan` | Plan a migration chain |
+| `neko schema migrate stub` | Generate a migration file stub |
+| `neko schema migrate verify` | Verify a migration chain is well-formed |
+| `neko init <name>` | Scaffold a project (stub in v1.0 — requires monorepo) |
+
+## Invariants
+
+1. **`dispatch()` never calls `process.exit`** — only `run()` (the bin entry) does. Enforced by the test suite.
+2. **Every command returns an `EXIT_CODES` value** — `SUCCESS (0)`, `USAGE_ERROR (1)`, `LOGICAL_FAILURE (2)`, `IO_ERROR (3)`, `INTERNAL_ERROR (5)`.
+3. **`--json` flag** produces machine-readable output for all schema commands.
+4. **Stdout/stderr writers are injected** — `buildCli(opts)` accepts `{ stdout, stderr }` so all output is capturable in tests without subprocess spawn.
+5. **Test coverage: 504 tests, 19 test files.**
+
+## What is in scope (v1.0)
+
+- `neko schema *` command group (8 verbs)
+- Commander-based argv parsing + dispatch
+- JSON output mode (`--json`)
+- Programmatic API (`dispatch`, `buildCli`, `EXIT_CODES`)
+
+## What is NOT in scope (v1.0)
+
+- Plugin system (packages registering their own subcommands) → future
+- `neko init` fully wired to published project templates → future
+- `neko new <kind> <name>` scaffolding → future
+- `neko lint`, `neko sim`, `neko codex` → those packages not yet published
+- Interactive prompt UX (clack) → future

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@nekostack/cli",
+  "version": "1.0.0",
+  "private": false,
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/cli.js",
+  "types": "./dist/cli.d.ts",
+  "bin": {
+    "neko": "./bin/neko"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "docs/*.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint ."
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "tsx": "^4.19.2"
+  },
+  "peerDependencies": {
+    "@nekostack/schema": "^1.0.0"
+  },
+  "devDependencies": {
+    "@nekostack/schema": "*",
+    "@nekostack/templates": "*",
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}