@poetics/cli 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jack James
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @poetics/cli
 
-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 poetics command-line interface, with --json output for agents.
+
+Part of [Poetics](../../README.md). Pre-alpha: see [architecture](../../docs/architecture.md) for what is built and what is stubbed.

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

package/dist/bin.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { run } from "./run.js";
+process.exitCode = await run(process.argv.slice(2), {
+    out: (text) => process.stdout.write(`${text}\n`),
+    err: (text) => process.stderr.write(`${text}\n`),
+});
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B,OAAO,CAAC,QAAQ,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;IAClD,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC;IAChD,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC;CACjD,CAAC,CAAC"}

package/dist/commands.d.ts

@@ -0,0 +1,8 @@
+export interface CommandSpec {
+    name: string;
+    usage: string;
+    summary: string;
+}
+/** The CLI surface from docs/plan.md, "Developer workflow and tooling". */
+export declare const COMMANDS: readonly CommandSpec[];
+//# sourceMappingURL=commands.d.ts.map

package/dist/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,2EAA2E;AAC3E,eAAO,MAAM,QAAQ,EAAE,SAAS,WAAW,EAU1C,CAAC"}

package/dist/commands.js

@@ -0,0 +1,13 @@
+/** The CLI surface from docs/plan.md, "Developer workflow and tooling". */
+export const COMMANDS = [
+    { name: "init", usage: "poetics init [--agents]", summary: "Detect React and Svelte, write config, index the repo and backfill history from git" },
+    { name: "index", usage: "poetics index", summary: "Incremental re-index of changed files; run by the git hook" },
+    { name: "log", usage: "poetics log <unit>", summary: "Version history of one unit, with rationale and commits" },
+    { name: "why", usage: "poetics why <unit>", summary: "The rationale chain that led to the current version" },
+    { name: "impact", usage: "poetics impact [ref]", summary: "Components whose closure changed since a branch or commit" },
+    { name: "diff", usage: "poetics diff <unit> <a> <b>", summary: "Semantic diff between two versions of a unit" },
+    { name: "verify", usage: "poetics verify [--since <ref>]", summary: "List unverified units, stale docs and unresolved edges, and unrecorded changes since a ref; non-zero exit for CI" },
+    { name: "coverage", usage: "poetics coverage", summary: "How much of the codebase .poetics/ covers, against policy thresholds" },
+    { name: "docs", usage: "poetics docs sync", summary: "Write stored docs into TSDoc and @component comments" },
+];
+//# sourceMappingURL=commands.js.map

package/dist/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAMA,2EAA2E;AAC3E,MAAM,CAAC,MAAM,QAAQ,GAA2B;IAC9C,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,yBAAyB,EAAE,OAAO,EAAE,qFAAqF,EAAE;IAClJ,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,4DAA4D,EAAE;IAChH,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,oBAAoB,EAAE,OAAO,EAAE,yDAAyD,EAAE;IAChH,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,oBAAoB,EAAE,OAAO,EAAE,qDAAqD,EAAE;IAC5G,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,sBAAsB,EAAE,OAAO,EAAE,2DAA2D,EAAE;IACvH,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,6BAA6B,EAAE,OAAO,EAAE,8CAA8C,EAAE;IAC/G,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,gCAAgC,EAAE,OAAO,EAAE,kHAAkH,EAAE;IACxL,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,kBAAkB,EAAE,OAAO,EAAE,sEAAsE,EAAE;IAChI,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,EAAE,OAAO,EAAE,sDAAsD,EAAE;CAC9G,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { CommandSpec } from "./commands.ts";
+export { COMMANDS } from "./commands.ts";
+export type { Io } from "./run.ts";
+export { VERSION, run } from "./run.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,YAAY,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { COMMANDS } from "./commands.js";
+export { VERSION, run } from "./run.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC"}

package/dist/run.d.ts

@@ -0,0 +1,8 @@
+export interface Io {
+    out(text: string): void;
+    err(text: string): void;
+}
+export declare const VERSION: string;
+/** Exit codes: 0 ok, 1 findings (e.g. verify), 2 usage or not-implemented. */
+export declare function run(argv: readonly string[], io: Io): Promise<number>;
+//# sourceMappingURL=run.d.ts.map

package/dist/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,EAAE;IACjB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAGD,eAAO,MAAM,OAAO,EAAE,MAEb,CAAC;AAEV,8EAA8E;AAC9E,wBAAsB,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA6B1E"}

package/dist/run.js

@@ -0,0 +1,43 @@
+import { readFileSync } from "node:fs";
+import { NotImplementedError } from "@poetics/core";
+import { COMMANDS } from "./commands.js";
+// src/ and dist/ both sit one level below package.json.
+export const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+/** Exit codes: 0 ok, 1 findings (e.g. verify), 2 usage or not-implemented. */
+export async function run(argv, io) {
+    const json = argv.includes("--json");
+    const args = argv.filter((arg) => arg !== "--json");
+    const [name] = args;
+    if (name === undefined || name === "help" || name === "--help" || name === "-h") {
+        io.out(json ? JSON.stringify({ version: VERSION, commands: COMMANDS }) : helpText());
+        return 0;
+    }
+    if (name === "--version" || name === "-v") {
+        io.out(json ? JSON.stringify({ version: VERSION }) : VERSION);
+        return 0;
+    }
+    const command = COMMANDS.find((spec) => spec.name === name);
+    if (!command) {
+        report(io, json, { error: "unknown-command", message: `Unknown command: ${name}. Run poetics help.` });
+        return 2;
+    }
+    try {
+        throw new NotImplementedError(`poetics ${command.name}`);
+    }
+    catch (error) {
+        if (error instanceof NotImplementedError) {
+            report(io, json, { error: "not-implemented", command: command.name, message: error.message });
+            return 2;
+        }
+        throw error;
+    }
+}
+function report(io, json, payload) {
+    io.err(json ? JSON.stringify(payload) : payload.message);
+}
+function helpText() {
+    const width = Math.max(...COMMANDS.map((command) => command.usage.length));
+    const lines = COMMANDS.map((command) => `  ${command.usage.padEnd(width)}  ${command.summary}`);
+    return [`poetics ${VERSION}`, "", "Usage:", ...lines, "", "Every command accepts --json for structured output."].join("\n");
+}
+//# sourceMappingURL=run.js.map

package/dist/run.js.map

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

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@poetics/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "The poetics command-line interface, with --json output for agents.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Pixerate/poetics.git",
+    "directory": "packages/cli"
+  },
+  "engines": {
+    "node": ">=24.15.0"
+  },
+  "exports": {
+    ".": {
+      "poetics-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/.tsbuildinfo"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "bin": {
+    "poetics": "./dist/bin.js"
+  },
+  "dependencies": {
+    "@poetics/core": "0.2.0",
+    "@poetics/store": "0.2.0"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  }
 }