peaks-loop 4.1.3 → 4.1.4

package/dist/cli/commands/release-watch-command.js

@@ -0,0 +1,44 @@
+// src/cli/commands/release-watch-command.ts
+//
+// `peaks release watch` — the watch-window status of the promoted release.
+// Split out of `release-commands.ts`; the verb name, its options, the rounded
+// `percentComplete` on the envelope and the `readyForDone` next-action rule are
+// unchanged.
+import { readReleaseState, watchWindow } from '../../services/release/release-state.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { resolveReleaseProjectRoot } from './release-command-shared.js';
+function runReleaseWatch(io, opts) {
+    const projectRoot = resolveReleaseProjectRoot(opts.project);
+    const state = readReleaseState(projectRoot);
+    if (state.active === null) {
+        printResult(io, fail('release.watch', 'NO_ACTIVE', 'no active release to watch', { projectRoot }, [
+            'Run `peaks release plan <version>` to start one.'
+        ]), opts.json ?? false);
+        return;
+    }
+    const win = watchWindow(state.active);
+    const readyForDone = win.percentComplete >= 1.0;
+    printResult(io, ok('release.watch', {
+        projectRoot,
+        version: state.active.version,
+        currentStage: state.active.currentStage,
+        window: {
+            elapsedMs: win.elapsedMs,
+            remainingMs: win.remainingMs,
+            windowMs: win.windowMs,
+            percentComplete: Math.round(win.percentComplete * 100) / 100
+        },
+        readyForDone
+    }, readyForDone
+        ? ['Watch window complete. Run `peaks release done` to mark the release done.']
+        : []), opts.json ?? false);
+}
+export function registerReleaseWatchCommand(release, io) {
+    addJsonOption(release
+        .command('watch')
+        .description('Show the watch window status for the current promoted release. ' +
+        '24h window from promoted-at. After the window, run `peaks release done` ' +
+        'to mark the release complete.')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => runReleaseWatch(io, opts));
+}

package/dist/cli/commands/sediment-argv-flags.d.ts

@@ -0,0 +1,54 @@
+/** Typed accessor over the flag map produced by `parseFlags`.
+ *
+ * `parseFlags` internally stores every flag with at least one value as a
+ * `string[]`. A flag with no following non-flag token (e.g. `--apply`,
+ * `--dry-run`) is recorded as `true`. This helper exposes three typed
+ * accessors so call-sites don't have to re-narrow `unknown` or
+ * `string | boolean | string[]` on every read:
+ *
+ *   - `flags.list(name)`     → `string[]` (always an array; a single
+ *                              occurrence is wrapped to a 1-element
+ *                              array at parse time)
+ *   - `flags.bool(name)`     → `boolean` (presence-of flag; missing
+ *                              flag is `false`)
+ *   - `flags.maybeString(name)` → `string | undefined` (first value,
+ *                              or `undefined` if the flag was given
+ *                              as a bare boolean with no value)
+ *
+ * The dispatch layer (runSediment) was previously peppered with
+ * `typeof flags.x === "string"` / `Array.isArray(flags.x)` narrowing.
+ * With this helper the call-sites collapse to one-line reads and the
+ * raw flag map stops leaking across the runSediment boundary.
+ */
+export declare class ParsedFlags {
+    private readonly raw;
+    constructor(raw: Record<string, string[] | true>);
+    /** Always returns an array. Missing flag → []. Single-occurrence
+     *  flag → a 1-element array (parseFlags normalizes this). */
+    list(name: string): string[];
+    /** Presence-of a bare boolean flag. Missing → false. */
+    bool(name: string): boolean;
+    /** First value of a flag, or `undefined` if the flag is absent or
+     *  was given as a bare boolean. */
+    maybeString(name: string): string | undefined;
+}
+/** Parse an argv tail into positional args + flag map.
+ *
+ * Supports:
+ *   --flag value    → flags[flag] = [value, ...] (advance i by 1)
+ *   --flag          → flags[flag] = true        (when next token starts with `--` or is undefined)
+ *   --flag v1 --flag v2   → repeated `--flag` values are accumulated
+ *
+ * Internally stores all values as `string[]` (or `true` for a bare
+ * boolean flag). Use the `ParsedFlags` helper to read typed accessors.
+ *
+ * Repeatable flag handling (Task 15b): when the same `--key` appears
+ * consecutively (e.g. `--segment a --segment b --segment c`), values
+ * are accumulated into a single `string[]`. A single occurrence is
+ * normalized to a 1-element array so callers can use `.list(name)`
+ * uniformly without shape-narrowing on the call-site.
+ */
+export declare function parseFlags(argv: string[]): {
+    positional: string[];
+    flags: ParsedFlags;
+};

package/dist/cli/commands/sediment-argv-flags.js

@@ -0,0 +1,116 @@
+// src/cli/commands/sediment-argv-flags.ts
+//
+// The argv tail parser `peaks skill sediment` drives every verb with: the raw
+// flag map and the typed accessors over it. Split out of
+// `sediment-commands.ts`, which re-exports both symbols so its public surface
+// is unchanged.
+/** Typed accessor over the flag map produced by `parseFlags`.
+ *
+ * `parseFlags` internally stores every flag with at least one value as a
+ * `string[]`. A flag with no following non-flag token (e.g. `--apply`,
+ * `--dry-run`) is recorded as `true`. This helper exposes three typed
+ * accessors so call-sites don't have to re-narrow `unknown` or
+ * `string | boolean | string[]` on every read:
+ *
+ *   - `flags.list(name)`     → `string[]` (always an array; a single
+ *                              occurrence is wrapped to a 1-element
+ *                              array at parse time)
+ *   - `flags.bool(name)`     → `boolean` (presence-of flag; missing
+ *                              flag is `false`)
+ *   - `flags.maybeString(name)` → `string | undefined` (first value,
+ *                              or `undefined` if the flag was given
+ *                              as a bare boolean with no value)
+ *
+ * The dispatch layer (runSediment) was previously peppered with
+ * `typeof flags.x === "string"` / `Array.isArray(flags.x)` narrowing.
+ * With this helper the call-sites collapse to one-line reads and the
+ * raw flag map stops leaking across the runSediment boundary.
+ */
+export class ParsedFlags {
+    raw;
+    constructor(raw) {
+        this.raw = raw;
+    }
+    /** Always returns an array. Missing flag → []. Single-occurrence
+     *  flag → a 1-element array (parseFlags normalizes this). */
+    list(name) {
+        const v = this.raw[name];
+        if (v === undefined)
+            return [];
+        if (v === true)
+            return [];
+        return v;
+    }
+    /** Presence-of a bare boolean flag. Missing → false. */
+    bool(name) {
+        const v = this.raw[name];
+        if (v === undefined)
+            return false;
+        // A flag given as `--name <value>` is also "present" (it just happens
+        // to carry values too). Existing call-sites that want `--dry-run`
+        // semantics care about presence, not whether values are attached.
+        return true;
+    }
+    /** First value of a flag, or `undefined` if the flag is absent or
+     *  was given as a bare boolean. */
+    maybeString(name) {
+        const v = this.raw[name];
+        if (v === undefined)
+            return undefined;
+        if (v === true)
+            return undefined;
+        return v[0];
+    }
+}
+/** Parse an argv tail into positional args + flag map.
+ *
+ * Supports:
+ *   --flag value    → flags[flag] = [value, ...] (advance i by 1)
+ *   --flag          → flags[flag] = true        (when next token starts with `--` or is undefined)
+ *   --flag v1 --flag v2   → repeated `--flag` values are accumulated
+ *
+ * Internally stores all values as `string[]` (or `true` for a bare
+ * boolean flag). Use the `ParsedFlags` helper to read typed accessors.
+ *
+ * Repeatable flag handling (Task 15b): when the same `--key` appears
+ * consecutively (e.g. `--segment a --segment b --segment c`), values
+ * are accumulated into a single `string[]`. A single occurrence is
+ * normalized to a 1-element array so callers can use `.list(name)`
+ * uniformly without shape-narrowing on the call-site.
+ */
+export function parseFlags(argv) {
+    const positional = [];
+    const rawFlags = {};
+    for (let i = 0; i < argv.length; i++) {
+        // `as string`, not `!`: the loop bound is `argv.length`, so these reads are
+        // in range — the toolchain just cannot see that through the index signature.
+        const a = argv[i];
+        if (a.startsWith('--')) {
+            const k = a.slice(2);
+            const v = argv[i + 1];
+            if (v === undefined || v.startsWith('--')) {
+                rawFlags[k] = true;
+            }
+            else {
+                // Capture first value, then look ahead for `--k <value>` repeats.
+                const values = [v];
+                i += 2;
+                while (i < argv.length &&
+                    argv[i] === `--${k}` &&
+                    i + 1 < argv.length &&
+                    !argv[i + 1].startsWith('--')) {
+                    values.push(argv[i + 1]);
+                    i += 2;
+                }
+                // Back up one — the outer for-loop will i++ past the flag, so the
+                // next iteration sees the next real token.
+                i--;
+                rawFlags[k] = values;
+            }
+        }
+        else {
+            positional.push(a);
+        }
+    }
+    return { positional, flags: new ParsedFlags(rawFlags) };
+}

package/dist/cli/commands/sediment-command-shared.d.ts

@@ -0,0 +1,15 @@
+import type { ParsedFlags } from './sediment-argv-flags.js';
+/** The `{ ok, error?, data? }` envelope every sediment verb returns. */
+export interface CliResult {
+    ok: boolean;
+    error?: string;
+    data?: unknown;
+}
+/** One parsed argv tail: the pool home, the positionals and the flag accessors. */
+export type SedimentContext = {
+    readonly home: string;
+    readonly positional: string[];
+    readonly flags: ParsedFlags;
+};
+/** A verb implementation. `runSediment` owns the error envelope around it. */
+export type SedimentVerb = (ctx: SedimentContext) => CliResult | Promise<CliResult>;

package/dist/cli/commands/sediment-command-shared.js

@@ -0,0 +1,5 @@
+// src/cli/commands/sediment-command-shared.ts
+//
+// The envelope and dispatch shapes every `peaks skill sediment` verb handler
+// shares. Split out of `sediment-commands.ts`.
+export {};

package/dist/cli/commands/sediment-commands.d.ts

@@ -1,64 +1,40 @@
+/**
+ * `peaks skill sediment <verb>` — Sediment pool CLI primitives.
+ *
+ * Slices 2026-07-04-cli-15a (Task 15a) and 2026-07-04-cli-15b (Task 15b)
+ * of the 18-verb plan. This file implements 8 of 18 verbs:
+ *
+ *   Task 15a:
+ *     add-segment   — scaffold ~/.peaks/skills/segments/<name>/SKILL.md
+ *     add-bee       — write ~/.peaks/skills/bees/<name>/manifest.json
+ *     list          — read index.json via readPool
+ *     rebuild-index — rewrite index.json from filesystem state
+ *
+ *   Task 15b:
+ *     refine-bee    — append a NL-described patch to an existing bee manifest
+ *     clone-bee     — duplicate an existing bee to a new name, status reset
+ *     promote       — flip candidate → stable when PromotionGate passes
+ *     retire        — flip → retired, optionally record a reason
+ *
+ * Other verbs (dispose / releases / release-show / release-diff / export /
+ * import / gc-blobs / search / recent / show) return
+ * `{ ok: false, error: "UNKNOWN_VERB: …" }` until Tasks 15c / 15d fill them.
+ *
+ * The CLI boundary is runSediment(argv, { home }): it returns a
+ * `{ ok, error?, data? }` envelope so program.ts can render the result
+ * as JSON via peaks-cli's existing printResult primitive.
+ *
+ * The verb bodies live beside this file — `sediment-pool-commands.ts` (the
+ * pool verbs), `sediment-release-commands.ts` (the retained-release verbs)
+ * and `sediment-query-commands.ts` (the read-only verbs) — with the argv
+ * parser in `sediment-argv-flags.ts`. This module owns the dispatch table,
+ * `parseFlags`' re-export and the commander registration.
+ */
 import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
-export interface CliResult {
-    ok: boolean;
-    error?: string;
-    data?: unknown;
-}
-/** Typed accessor over the flag map produced by `parseFlags`.
- *
- * `parseFlags` internally stores every flag with at least one value as a
- * `string[]`. A flag with no following non-flag token (e.g. `--apply`,
- * `--dry-run`) is recorded as `true`. This helper exposes three typed
- * accessors so call-sites don't have to re-narrow `unknown` or
- * `string | boolean | string[]` on every read:
- *
- *   - `flags.list(name)`     → `string[]` (always an array; a single
- *                              occurrence is wrapped to a 1-element
- *                              array at parse time)
- *   - `flags.bool(name)`     → `boolean` (presence-of flag; missing
- *                              flag is `false`)
- *   - `flags.maybeString(name)` → `string | undefined` (first value,
- *                              or `undefined` if the flag was given
- *                              as a bare boolean with no value)
- *
- * The dispatch layer (runSediment) was previously peppered with
- * `typeof flags.x === "string"` / `Array.isArray(flags.x)` narrowing.
- * With this helper the call-sites collapse to one-line reads and the
- * raw flag map stops leaking across the runSediment boundary.
- */
-export declare class ParsedFlags {
-    private readonly raw;
-    constructor(raw: Record<string, string[] | true>);
-    /** Always returns an array. Missing flag → []. Single-occurrence
-     *  flag → a 1-element array (parseFlags normalizes this). */
-    list(name: string): string[];
-    /** Presence-of a bare boolean flag. Missing → false. */
-    bool(name: string): boolean;
-    /** First value of a flag, or `undefined` if the flag is absent or
-     *  was given as a bare boolean. */
-    maybeString(name: string): string | undefined;
-}
-/** Parse an argv tail into positional args + flag map.
- *
- * Supports:
- *   --flag value    → flags[flag] = [value, ...] (advance i by 1)
- *   --flag          → flags[flag] = true        (when next token starts with `--` or is undefined)
- *   --flag v1 --flag v2   → repeated `--flag` values are accumulated
- *
- * Internally stores all values as `string[]` (or `true` for a bare
- * boolean flag). Use the `ParsedFlags` helper to read typed accessors.
- *
- * Repeatable flag handling (Task 15b): when the same `--key` appears
- * consecutively (e.g. `--segment a --segment b --segment c`), values
- * are accumulated into a single `string[]`. A single occurrence is
- * normalized to a 1-element array so callers can use `.list(name)`
- * uniformly without shape-narrowing on the call-site.
- */
-export declare function parseFlags(argv: string[]): {
-    positional: string[];
-    flags: ParsedFlags;
-};
+import type { CliResult } from './sediment-command-shared.js';
+export { ParsedFlags, parseFlags } from './sediment-argv-flags.js';
+export type { CliResult } from './sediment-command-shared.js';
 /** Dispatch a sediment verb argv to the matching implementation.
  *
  * Returns { ok: true, data? } on success and { ok: false, error }