@animus-ui/cli 0.1.11

package/README.md

@@ -0,0 +1,75 @@
+# @animus-ui/cli
+
+Standalone Animus extraction CLI — one-shot builds and artifact emission
+for any build system. `animus build` drives the same extraction session the
+bundler plugins use and publishes a deterministic, fixed-path artifact set
+for CI gates, non-JS orchestrators, and tooling.
+
+If you are on a supported bundler, you want a transform driver instead:
+[`@animus-ui/vite-plugin`](../vite-plugin),
+[`@animus-ui/next-plugin`](../next-plugin), or
+[`@animus-ui/unplugin`](../unplugin) (rollup/esbuild/rspack/webpack). The
+CLI's artifacts do not transform your sources — see the
+[standalone extraction contract](https://github.com/codecaaron/animus/blob/main/docs/standalone-extraction.md)
+for why the transform is mandatory.
+
+## Install
+
+```bash
+npm install --save-dev @animus-ui/cli
+```
+
+Requires Node `>=22.12.0`. Native engine binaries ship for darwin-arm64,
+linux-x64-gnu, and linux-arm64-gnu; the CLI exits 3 with remediation text
+on unsupported platforms.
+
+## Usage
+
+<!-- source lane: e2e/rollup-app/package.json `verify:build`; verified by running it in the lane (exit 0: "build complete: 10 components from 15 files") -->
+
+```bash
+animus build --root . --system ./src/ds.ts --strict
+animus watch --root . --system ./src/ds.ts
+animus print-config --root . --system ./src/ds.ts
+```
+
+Configuration lives in `animus.config.{json,mjs,js,ts}` (probed in that
+order; `.ts` needs Node >= 23.6 native type stripping — older runtimes get
+a guided error naming the `.mjs`/`.json` remedy). Flags override file
+values; `--exclude` merges. `animus print-config` prints the fully resolved
+configuration as JSON on stdout with per-key provenance.
+
+Stream discipline is a contract: **stdout carries machine output only**;
+every human-facing line goes to stderr.
+
+## Exit codes
+
+| Code | Meaning                                                                                         |
+| ---- | ----------------------------------------------------------------------------------------------- |
+| 0    | Success — artifact set published and self-consistent                                            |
+| 1    | Extraction failure (error diagnostics, `--strict` escalation, zero files, structural emptiness) |
+| 2    | Config/usage error (unknown key, unresolvable system path, lock conflict)                       |
+| 3    | Engine/environment failure (native engine load, consistency-check failure)                      |
+
+`animus watch` adds: 130 on SIGINT, 143 on SIGTERM (lock released,
+last-good artifacts kept), and 3 under `--fail-on-degraded` when any root
+cannot be watched. Watch readiness is an explicit stderr event: wait for
+the `watch ready` line before starting dependent steps.
+
+Silent-empty success is impossible: system-load failure, zero discovered
+files, and structural emptiness are fatal in every mode.
+
+## Artifacts
+
+`animus build` publishes to `--out-dir` (default `<root>/.animus/` —
+`.gitignore` it) at fixed paths: `styles.css`, `system-props.js`,
+`manifest.json`, and `commit.json` — written last, carrying a content hash
+per payload, so one read verifies set completeness and freshness. Bytes are
+deterministic and identity-free; `lock.json` is a single-writer advisory
+lock that fails loud. The full contract, including the consistency-check
+recipe for non-JS orchestrators, is in the
+[standalone extraction contract](https://github.com/codecaaron/animus/blob/main/docs/standalone-extraction.md).
+
+## License
+
+MIT

package/bin/animus.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// Thin shebang shim — the built entry owns everything (arg parsing, exit
+// codes, stream discipline). Kept as a plain file so the bin needs no
+// build-time banner injection.
+import('../dist/index.mjs').then((mod) => mod.main());

package/dist/build.d.ts

@@ -0,0 +1,62 @@
+/**
+ * `animus build` — one-shot extraction over the SAME drive loop every
+ * driver uses (`ExtractionSession`; NS1/NS4: no second composition), then
+ * export of the raw payloads to the fixed-path deterministic artifact
+ * contract (design D3) via the CLI writer. The one-shot session tree is
+ * removed after export — no session-dir accumulation per CI run.
+ *
+ * Failure policy (design D5): silent-empty success is impossible —
+ * system-load failure, zero discovered files, and structural emptiness are
+ * fatal in EVERY mode, independent of `strict`.
+ *
+ * The preflight, session construction, and shared-state publication steps
+ * are exported helpers: `animus watch` (watch.ts) runs the same checks and
+ * the same writer path per publication instead of forking them.
+ */
+import { ExtractionSession } from '@animus-ui/extract/session';
+import type { ResolvedCliConfig } from './config';
+/** Thrown for failures whose exit class is "extraction failure" (1). */
+export declare class ExtractionFailure extends Error {
+}
+/** Thrown for failures whose exit class is "config/usage error" (2). */
+export declare class UsageFailure extends Error {
+}
+/** Thrown for failures whose exit class is "engine/environment" (3). */
+export declare class EnvironmentFailure extends Error {
+}
+/** The CLI's one stderr prefix convention (stdout stays machine-only) —
+ *  shared with watch.ts. */
+export declare const err: (...parts: unknown[]) => void;
+export interface BuildResult {
+    outDir: string;
+    componentCount: number;
+    fileCount: number;
+}
+/** Preflight shared by build and watch: root and system-module existence
+ *  are usage errors (exit 2) decided before any engine work; a missing
+ *  platform binary is an environment failure (exit 3) surfaced with the
+ *  loader's own remediation text. */
+export declare function runPreflight(config: ResolvedCliConfig): Promise<void>;
+/** The one CLI session shape: self-ingestion guard applied (an outDir
+ *  inside the root is force-excluded from discovery, loudly), driver label
+ *  and root authority set, tsconfig `paths` harvested as the alias source
+ *  (no live bundler config exists for this driver). */
+export declare function createCliSession(config: ResolvedCliConfig): ExtractionSession;
+export interface PublishOutcome {
+    componentCount: number;
+    fileCount: number;
+}
+/**
+ * Publish the session's shared-state payloads through the deterministic
+ * CLI writer (design D3) — the SINGLE publication path for build and every
+ * watch cycle. Zero analyzed files, an unreadable manifest, and structural
+ * emptiness throw ExtractionFailure (silent-empty success is impossible);
+ * a post-publish consistency failure throws EnvironmentFailure.
+ */
+export declare function publishSharedPayloads(config: ResolvedCliConfig, session: ExtractionSession): PublishOutcome;
+/** Discovery-outcome report (stderr): per-specifier accounting plus
+ *  dead-pattern visibility — a user exclusion that matched nothing is
+ *  named instead of silently inert. */
+export declare function reportDiscoveryOutcomes(config: ResolvedCliConfig, session: ExtractionSession): void;
+export declare function runBuild(config: ResolvedCliConfig): Promise<BuildResult>;
+//# sourceMappingURL=build.d.ts.map

package/dist/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAOH,OAAO,EAEL,iBAAiB,EAMlB,MAAM,4BAA4B,CAAC;AAUpC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAElD,wEAAwE;AACxE,qBAAa,iBAAkB,SAAQ,KAAK;CAAG;AAC/C,wEAAwE;AACxE,qBAAa,YAAa,SAAQ,KAAK;CAAG;AAC1C,wEAAwE;AACxE,qBAAa,kBAAmB,SAAQ,KAAK;CAAG;AAEhD;4BAC4B;AAC5B,eAAO,MAAM,GAAG,aAAc,OAAO,EAAE,KAAG,IACL,CAAC;AAEtC,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;qCAGqC;AACrC,wBAAsB,YAAY,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA0B3E;AAED;;;uDAGuD;AACvD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,iBAAiB,GAAG,iBAAiB,CA8B7E;AAED,MAAM,WAAW,cAAc;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,iBAAiB,GACzB,cAAc,CAyEhB;AAED;;uCAEuC;AACvC,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,iBAAiB,GACzB,IAAI,CAgBN;AAED,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,iBAAiB,GACxB,OAAO,CAAC,WAAW,CAAC,CA6CtB"}

package/dist/config.d.ts

@@ -0,0 +1,50 @@
+/**
+ * CLI config resolution — the third driver over the shared option core
+ * (shared-driver-config): documented precedence flags > config file >
+ * defaults, one root authority, explicit emission mode (the CLI never
+ * sniffs NODE_ENV), and a fully inspectable resolved projection for
+ * `--print-config`.
+ */
+import type { AnimusCoreOptions, AnimusMode, OptionProvenance } from '@animus-ui/extract/pipeline';
+/** Config filenames probed in order under the config-search root. */
+export declare const CONFIG_FILENAMES: readonly ['animus.config.json', 'animus.config.mjs', 'animus.config.js', 'animus.config.ts'];
+/** The `cli:` driver namespace of the shared config schema. */
+export interface CliNamespaceOptions {
+    /** Artifact output directory, relative to the root. @default '.animus' */
+    outDir?: string;
+}
+export interface CliFlags {
+    system?: string;
+    root?: string;
+    config?: string;
+    outDir?: string;
+    strict?: boolean;
+    verbose?: boolean;
+    mode?: string;
+    targets?: string;
+    exclude?: string[];
+}
+export interface ResolvedCliConfig {
+    driver: 'cli';
+    /** Absolute root every relative input resolves against. */
+    root: string;
+    /** Absolute path of the config file consulted, or null. */
+    configFile: string | null;
+    /** The effective core options handed to the session. */
+    options: AnimusCoreOptions;
+    /** Absolute artifact output directory. */
+    outDir: string;
+    /** Effective merged exclusion pattern list (defaults ∪ user). */
+    excludePatterns: readonly string[];
+    mode: AnimusMode;
+    provenance: Record<string, OptionProvenance>;
+}
+/**
+ * Resolve the effective CLI configuration. Precedence: flags > config file
+ * > documented defaults. Scalar flags override; `--exclude` values merge
+ * (exclusion semantics are merge-only by contract).
+ */
+export declare function resolveCliConfig(flags: CliFlags, cwd: string): Promise<ResolvedCliConfig>;
+/** The `--print-config` projection: everything effective, nothing hidden. */
+export declare function projectResolvedConfig(config: ResolvedCliConfig): Record<string, unknown>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH,OAAO,KAAK,EACV,iBAAiB,EACjB,UAAU,EACV,gBAAgB,EACjB,MAAM,6BAA6B,CAAC;AAErC,qEAAqE;AACrE,eAAO,MAAM,gBAAgB,YAC3B,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,CACV,CAAC;AAEX,+DAA+D;AAC/D,MAAM,WAAW,mBAAmB;IAClC,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,KAAK,CAAC;IACd,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,wDAAwD;IACxD,OAAO,EAAE,iBAAiB,CAAC;IAC3B,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,IAAI,EAAE,UAAU,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC9C;AAsCD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,QAAQ,EACf,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,iBAAiB,CAAC,CAqI5B;AAED,6EAA6E;AAC7E,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,iBAAiB,GACxB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiBzB"}