halfcycle 0.3.12 → 0.3.13

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "halfcycle",
-  "version": "0.3.12",
+  "version": "0.3.13",
   "description": "Halfcycle Method bundle — resolution-stub slash commands, remote method-delivery registration, and governance-hook wiring for a Halfcycle engagement repo. It ships NO worker role files: a project's roles are authored from that project's own recorded decisions at orchestration kickoff (FX-2, W3-F-27).",
   "commands": [
     {

package/dist/banner-facts.d.ts

@@ -0,0 +1,73 @@
+/**
+ * WHAT THE BANNER SAYS ABOUT THIS RUN — the impure half of `banner.ts`.
+ *
+ * The banner's whole claim is that it reads the repository before it says anything: the
+ * version, the Claude Code beside it, the project it is standing in, whether that project
+ * has ever been installed, and which plane it will talk to. All five are knowable before a
+ * byte is written, and every one of them is a probe that can fail.
+ *
+ * **A FACT THAT CANNOT BE ESTABLISHED IS OMITTED, NEVER GUESSED AND NEVER APOLOGISED FOR.**
+ * No `unknown`, no `n/a`, no empty row. A developer without `claude` on their PATH is the
+ * ordinary case, not a fault to report in a decorative block, and the fact column simply
+ * has one fewer row. That rule is why every probe below is wrapped and why each returns
+ * `undefined` rather than a placeholder string.
+ *
+ * **NOTHING HERE MAY THROW.** It runs first, before argument parsing has decided what the
+ * command even is, so an exception raised while composing a logo would take down a
+ * `check-drift` that was going to work. `openingBannerContent` is total.
+ *
+ * INV-001: Node builtins and modules inside this package only.
+ */
+import { type BannerContent } from './banner.js';
+/**
+ * The address on the banner's last line.
+ *
+ * This is the BRAND's front door, not the plane this run talks to — those are different
+ * questions and the `Plane` fact answers the second one. A developer pointed at a
+ * development plane should still be told where Halfcycle is.
+ */
+export declare const BRAND_URL = "halfcycle.ai";
+/**
+ * The tagline, verbatim (operator, 2026-09-01).
+ *
+ * The web surfaces deliberately say something else; that divergence is recorded as a
+ * decision in the phase document, so anybody who arrives here intending to make the two
+ * agree should read it first rather than treating this as drift.
+ */
+export declare const TAGLINE: readonly string[];
+/** The same tagline stacked for the narrow cut, where the second line does not fit. */
+export declare const TAGLINE_NARROW: readonly string[];
+/** This package's own version, or `undefined` if the manifest cannot be read. */
+export declare function bundleVersion(): string | undefined;
+/**
+ * The locally installed Claude Code version, or `undefined`.
+ *
+ * A short timeout and a swallowed failure, for the reason the install path's own version
+ * check gives: `claude` missing from PATH is the normal case for a desktop-app user, and
+ * treating it as a problem would put a warning on a correct install. This is the second
+ * place in the CLI that asks; they are deliberately separate calls because that one exists
+ * to WARN about an old version and this one exists to state a fact, and collapsing them
+ * would make the banner responsible for a compatibility check.
+ */
+export declare function claudeCodeVersion(): string | undefined;
+/** Everything the fact collector is allowed to reach outside itself, so a test can hand it
+ *  a world instead of standing in one. */
+export interface FactProbes {
+    readonly bundleVersion: () => string | undefined;
+    readonly claudeCodeVersion: () => string | undefined;
+    readonly projectName: (dir: string) => string | undefined;
+    readonly commitCount: (dir: string) => number | null;
+    readonly installedVersion: (dir: string) => string | undefined;
+    readonly planeHost: (env: NodeJS.ProcessEnv) => string | undefined;
+}
+/** The real probes. Each one is separately replaceable, which is the point of the seam. */
+export declare const REAL_PROBES: FactProbes;
+/**
+ * The opening block's content for a run against `projectDir`.
+ *
+ * `projectDir` is the directory the command is about to act on — the install target, which
+ * is the current directory in the bare form and an argument otherwise. The banner names
+ * what the run will touch, not where the shell happens to be.
+ */
+export declare function openingBannerContent(projectDir: string, env?: NodeJS.ProcessEnv, probes?: FactProbes): BannerContent;
+//# sourceMappingURL=banner-facts.d.ts.map

package/dist/banner-facts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"banner-facts.d.ts","sourceRoot":"","sources":["../src/banner-facts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AASH,OAAO,EAAkB,KAAK,aAAa,EAAmB,MAAM,aAAa,CAAC;AAElF;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,iBAAiB,CAAC;AAExC;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,EAAE,SAAS,MAAM,EAGpC,CAAC;AAEF,uFAAuF;AACvF,eAAO,MAAM,cAAc,EAAE,SAAS,MAAM,EAI3C,CAAC;AAEF,iFAAiF;AACjF,wBAAgB,aAAa,IAAI,MAAM,GAAG,SAAS,CAOlD;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAWtD;AAED;0CAC0C;AAC1C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IACjD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IACrD,QAAQ,CAAC,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC1D,QAAQ,CAAC,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACrD,QAAQ,CAAC,gBAAgB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC/D,QAAQ,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,KAAK,MAAM,GAAG,SAAS,CAAC;CACpE;AAED,2FAA2F;AAC3F,eAAO,MAAM,WAAW,EAAE,UAqCzB,CAAC;AAQF;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,EAClB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,MAAM,GAAE,UAAwB,GAC/B,aAAa,CAmCf"}

package/dist/banner.d.ts

@@ -0,0 +1,188 @@
+/**
+ * THE `npx halfcycle` OPENING BANNER — the mark, the name, the tagline and the URL.
+ *
+ * This module is PURE: it takes content and an environment description and returns a
+ * string. Everything that touches the filesystem, git or a subprocess lives in
+ * `banner-facts.ts`, so the layout can be compared against its generator without a
+ * repository, a network or a clock being involved.
+ *
+ * ---------------------------------------------------------------------------
+ * WHERE THE ART COMES FROM, AND WHY IT IS NOT DRAWN HERE.
+ *
+ * `MARK_FULL` and `MARK_NARROW` below are the OUTPUT of `docs/design/cli-banner.mjs`,
+ * which supersamples the brand mark's real SVG geometry onto a character density ramp.
+ * They were produced by running it and are never edited by hand. `cli-banner-drift.test.ts`
+ * re-runs that generator and compares, and it also compares the generator's geometry
+ * numbers against the SVG they were read from — so the chain
+ * `Mark.tsx -> cli-banner.mjs -> the constants below` has a check at every link, and a
+ * change to the mark at either end fails the build rather than quietly shipping a logo
+ * that is no longer the logo.
+ *
+ * Because a copy of a generator's output is exactly the shape that rots, the constants
+ * carry NO layout decisions of their own beyond the glyphs: the column widths, the gap,
+ * the rule length and the centring below reproduce `render()` in that generator, and the
+ * drift test asserts the whole rendered block byte-for-byte, not just the art.
+ *
+ * ---------------------------------------------------------------------------
+ * THE FIVE RULES THIS FILE EXISTS TO HOLD.
+ *
+ *  1. **No dependency.** Raw ANSI, hand-written. The package ships to a client's disk and
+ *     its runtime dependency list is one entry long; a colour library is not worth a
+ *     second. Nothing here imports anything at all.
+ *  2. **Never a hard-coded foreground colour.** The mark, the fact values and the first
+ *     tagline line take the terminal's OWN foreground. A surface in this product has
+ *     already once been invisible on a light-mode machine because it chose its own ink.
+ *     Sixteen-colour ANSI and nothing else — no truecolor, no 256-colour cube — so it
+ *     resolves against whatever theme the developer already picked.
+ *  3. **Off when it should be off.** `--quiet`, a stdout that is not a TTY, `NO_COLOR`
+ *     and `TERM=dumb` each have a defined answer, and none of them is "art anyway".
+ *  4. **stdout, never stderr.** A banner on stderr turns a successful install into a red
+ *     block in half the tools that wrap it.
+ *  5. **Printable ASCII, with a fallback for the two glyphs that are not.** Only the rule
+ *     and the palette strip use box-drawing characters; on a console that cannot render
+ *     them the whole banner is put through `toAscii` instead of shipping mojibake.
+ */
+/**
+ * One size of the mark as characters.
+ *
+ * `discRows` is a row COUNT rather than a per-character map because the generator's
+ * output happens to split cleanly: every row is either wholly the solid top disc or
+ * wholly the outlined bottom ring, at both sizes. The drift test re-derives it from the
+ * generator instead of trusting that sentence, so if a geometry change ever mixes the two
+ * within one row the test says so rather than the banner silently mis-colouring.
+ */
+export interface MarkArt {
+    /** The generator's column count — lines are right-trimmed, so this is not their length. */
+    readonly width: number;
+    /** How many leading rows are the solid disc; the rest are the ring and the divider. */
+    readonly discRows: number;
+    readonly lines: readonly string[];
+}
+/** The accepted cut: 32 columns wide, 14 rows. Generated by `cli-banner.mjs`. */
+export declare const MARK_FULL: MarkArt;
+/** The narrow cut: the same geometry at 24 columns, 10 rows. Generated by `cli-banner.mjs`. */
+export declare const MARK_NARROW: MarkArt;
+/**
+ * The non-ASCII characters the banner is allowed to contain, and nothing else.
+ *
+ * The mark itself is printable ASCII by construction — that is what makes it survive a
+ * console in a legacy code page. These four are the entire remainder, which is what lets
+ * a test assert a closed vocabulary rather than a threshold.
+ */
+export interface GlyphSet {
+    /** The rule under the header. */
+    readonly rule: string;
+    /** One half of a palette block; the strip is eight pairs of these. */
+    readonly swatch: string;
+    /** The separator inside a composed fact value, and inside the one-line cut. */
+    readonly dot: string;
+    /** The dash in a fact value's aside. */
+    readonly dash: string;
+}
+export declare const UNICODE_GLYPHS: GlyphSet;
+/** What each of them becomes when the console cannot render it. */
+export declare const ASCII_GLYPHS: GlyphSet;
+/**
+ * Force `text` into printable ASCII.
+ *
+ * The four named glyphs get a chosen substitute; ANYTHING else outside printable ASCII
+ * becomes `?`. That last clause is not defensive dressing — a fact value carries a
+ * project directory's name, and a developer whose folder is called `café` on a console in
+ * a non-UTF-8 code page should see one question mark rather than two bytes of mojibake in
+ * the middle of the mark's alignment. Every substitution is length-preserving, so it
+ * cannot break the column arithmetic.
+ */
+export declare function toAscii(text: string): string;
+/**
+ * One labelled row of the fact column.
+ *
+ * `narrow` is both the value used in the narrow cut AND the marker that the fact belongs
+ * in it: a fact with no `narrow` is dropped there. Two of the five facts are, which is
+ * what makes the narrow block fit beside a mark half the width without clipping every
+ * value into meaninglessness.
+ */
+export interface BannerFact {
+    readonly label: string;
+    readonly value: string;
+    readonly narrow?: string;
+}
+export interface BannerContent {
+    /** `halfcycle@my-app` — split on the first `@` for colouring. */
+    readonly head: string;
+    readonly facts: readonly BannerFact[];
+    /** The tagline, one entry per line. The first line is bold, the rest dim. */
+    readonly tag: readonly string[];
+    /** The tagline re-wrapped for the narrow cut; falls back to `tag`. */
+    readonly tagNarrow?: readonly string[];
+    readonly url: string;
+    /** The version the one-line cut reports. */
+    readonly version: string;
+}
+/**
+ * `none` prints nothing at all; `line` is the single line a pipe or a CI log gets;
+ * `narrow` and `full` are the two art cuts.
+ */
+export type BannerCut = 'none' | 'line' | 'narrow' | 'full';
+/** What `process.stdout.columns` is taken to be when it does not report a usable width. */
+export declare const DEFAULT_COLUMNS = 80;
+/** Everything the banner needs to know about the world it is printing into. */
+export interface BannerEnvironment {
+    readonly columns?: number | undefined;
+    readonly isTTY?: boolean | undefined;
+    /** `--quiet` was passed. */
+    readonly quiet?: boolean | undefined;
+    readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+    /** `process.platform`; only the Windows console needs a different unicode answer. */
+    readonly platform?: string | undefined;
+}
+/**
+ * Which cut this run prints.
+ *
+ * The order is the order the reasons override each other: an explicit `--quiet` beats
+ * everything, then the shape of the output stream, then the width of the terminal.
+ */
+export declare function decideCut(environment?: BannerEnvironment): BannerCut;
+/**
+ * Is colour emitted?
+ *
+ * `FORCE_COLOR` is checked first and both ways, because it is the only explicit statement
+ * in the set: `FORCE_COLOR=0` turns colour off in a terminal that would otherwise have it,
+ * and any other value turns it on. Everything else is inference.
+ */
+export declare function decideColour(environment?: BannerEnvironment): boolean;
+/**
+ * Can this console render the rule and the palette strip?
+ *
+ * Everywhere but Windows, the locale answers: an explicitly non-UTF-8 `LANG`/`LC_ALL`
+ * means no, and an unset locale — the ordinary case under `npx` in a launcher-started
+ * terminal — is taken as yes. On Windows the locale says nothing about the console's code
+ * page, so the answer is the presence of a host known to run in UTF-8; the old
+ * `cmd.exe`/`powershell.exe` console is assumed to be a legacy code page, which is the
+ * conservative direction: the cost of being wrong is a mark drawn with `-` and `#`.
+ */
+export declare function decideUnicode(environment?: BannerEnvironment): boolean;
+/**
+ * The banner as a string, with no trailing newline. `''` means print nothing — the caller
+ * must not turn that into a blank line.
+ */
+export declare function renderBanner(content: BannerContent, environment?: BannerEnvironment): string;
+/** Somewhere to write the banner. `process.stdout` satisfies it; so does a test double. */
+export interface BannerSink {
+    write(chunk: string): unknown;
+}
+/**
+ * Print the banner — to the sink the caller names, which is always stdout.
+ *
+ * Nothing is written at all when the banner is suppressed, not even the newline: a
+ * `--quiet` run and a piped run should differ from an unsuppressed one by the banner, not
+ * by a blank line the next tool has to strip.
+ */
+export declare function printBanner(sink: BannerSink, content: BannerContent, environment?: BannerEnvironment): void;
+/**
+ * The environment as this process actually finds it.
+ *
+ * The one place `process` is read, so every other function here can be handed a
+ * description of a world instead of running in one.
+ */
+export declare function currentEnvironment(quiet: boolean): BannerEnvironment;
+//# sourceMappingURL=banner.d.ts.map

package/dist/banner.d.ts.map

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