@rasensio/aidlc 1.66.0 → 1.72.0

package/dist/hooks/guard.js

@@ -0,0 +1,108 @@
+/**
+ * The phase guard: a Claude Code `PreToolUse` hook that asks before a code file
+ * is edited while the instance claimed here is still being planned
+ * (hooks-carry-lifecycle-state/AC-11..AC-13).
+ *
+ * The opposite contract to the reviewer guard (`compile/reviewer-guard.ts`), on
+ * purpose. That one fails closed because it is a security boundary for an agent
+ * that must not write. This one enforces a process rule — "no code before the
+ * design is agreed" — and the risk named for it is a hook that blocks legitimate
+ * work. So it only ever *asks*, and every way it can fail is silence: the
+ * decision falls back to the normal permission flow, never to a block (design D5).
+ * Writes made through `Bash` are not seen; it is a guardrail, not a boundary.
+ *
+ * Design: design.md C3
+ *
+ * @module
+ */
+import { realpathSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { isWithin, toPosixRelative } from '../core/paths.js';
+import { PLANNING_PHASES, claimsHere, currentPhase, plainLine } from './lifecycle-context.js';
+/** The tools that write a file named in their input. */
+export const GUARDED_TOOLS = ['Edit', 'Write', 'MultiEdit', 'NotebookEdit'];
+function targetOf(toolInput) {
+    for (const key of ['file_path', 'notebook_path']) {
+        const value = toolInput[key];
+        if (typeof value === 'string' && value !== '')
+            return value;
+    }
+    return null;
+}
+/**
+ * The project root as written and as resolved through symlinks. Harnesses may
+ * name a file through either (macOS `/var` is `/private/var`), and a purely
+ * lexical test against only one form would call a project file "outside".
+ */
+function rootForms(projectRoot) {
+    const forms = [resolve(projectRoot)];
+    try {
+        const real = realpathSync(projectRoot);
+        if (real !== forms[0])
+            forms.push(real);
+    }
+    catch {
+        // keep the lexical form only
+    }
+    return forms;
+}
+/**
+ * Whether to ask before this tool call, from the raw `PreToolUse` payload.
+ *
+ * Null in every case but one: a guarded tool, writing a file inside the project
+ * and outside `.aidlc/`, while an instance claimed here is in ideation,
+ * requirements or design (AC-11, AC-12). Unreadable input is null, never a throw.
+ */
+export function guardDecision(projectRoot, raw) {
+    let input;
+    try {
+        input = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof input !== 'object' || input === null)
+        return null;
+    const { tool_name: toolName, tool_input: toolInput, cwd } = input;
+    if (typeof toolName !== 'string' || !GUARDED_TOOLS.includes(toolName))
+        return null;
+    if (typeof toolInput !== 'object' || toolInput === null)
+        return null;
+    const target = targetOf(toolInput);
+    if (target === null)
+        return null;
+    const base = typeof cwd === 'string' && isAbsolute(cwd) ? cwd : projectRoot;
+    const file = resolve(base, target);
+    const root = rootForms(projectRoot).find((r) => isWithin(r, file));
+    // The root itself is a directory, not a file anyone edits.
+    if (root === undefined || file === root || isWithin(join(root, '.aidlc'), file))
+        return null;
+    for (const instance of claimsHere(projectRoot)) {
+        const phase = currentPhase(projectRoot, instance);
+        if (phase === null || !PLANNING_PHASES.includes(phase))
+            continue;
+        const rel = toPosixRelative(root, file);
+        return {
+            instance,
+            phase,
+            file: rel,
+            reason: plainLine(`AIDLC: ${instance} is in the ${phase} phase; code is written in implementation. Edit ${rel} anyway?`),
+        };
+    }
+    return null;
+}
+/**
+ * Claude Code's `PreToolUse` answer for a decision. Always `ask` — never `deny`
+ * and never `allow` (AC-13): an `allow` would skip the permission prompt the
+ * user configured, which is not this hook's to waive.
+ */
+export function guardOutput(decision) {
+    return JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'ask',
+            permissionDecisionReason: decision.reason,
+        },
+    });
+}
+//# sourceMappingURL=guard.js.map

package/dist/hooks/guard.js.map

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

package/dist/hooks/install.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Installs the lifecycle hooks: the session-start hook for Claude Code and
+ * Codex, and the opt-in phase guard for Claude Code
+ * (hooks-carry-lifecycle-state/AC-14..AC-16, AC-20, AC-21).
+ *
+ * Identity is a trailing marker, as for the cost hooks, but a different one
+ * (design D9). With a shared marker `aidlc cost hooks status` would count a
+ * lifecycle hook as a cost hook and `cost hooks remove` would delete it. The cost
+ * installer matches `endsWith('#aidlc-cost-hook')`, which no command here
+ * satisfies, so neither installer sees the other's entries and the cost code is
+ * unchanged. The merge below is written again rather than generalised out of
+ * `cost/hooks/claude-code.ts` because it also writes Codex's file, and the cost
+ * installer's tests pin its exact behaviour.
+ *
+ * Codex trusts a hook by its content hash, and only the user's own config may
+ * record that hash (knowledge: `codex-hook-trust-model`). So this module writes
+ * the project's `.codex/hooks.json` and nothing else for Codex — never
+ * `~/.codex/`, never a trust hash — and writes only when the text would change,
+ * so installing twice cannot cost the user the trust they already gave.
+ *
+ * Design: design.md C4
+ *
+ * @module
+ */
+export type LifecyclePlatform = 'claude-code' | 'codex';
+export type LifecycleHook = 'session-start' | 'guard';
+export declare const LIFECYCLE_PLATFORMS: readonly LifecyclePlatform[];
+export declare const LIFECYCLE_HOOK_MARKER = "#aidlc-lifecycle-hook";
+export declare const GUARD_MATCHER = "Edit|Write|MultiEdit|NotebookEdit";
+/**
+ * The two hook commands for a platform. Both run through the cost-capture shim,
+ * which finds an absolute `node` and this project's CLI at run time and never
+ * consults `PATH` (cost-capture-goes-dark/AC-15) — a bare `aidlc` here would be a
+ * `PATH` lookup on every session start (design D1).
+ */
+export declare function lifecycleCommands(platform?: LifecyclePlatform): Record<LifecycleHook, string>;
+export declare function hookFilePath(projectRoot: string, platform: LifecyclePlatform): string;
+/** Whether the phase guard can be installed for a platform. */
+export declare function supportsGuard(platform: LifecyclePlatform): boolean;
+/** The step the user still owes before the platform runs the hook, or null. */
+export declare function trustStep(platform: LifecyclePlatform): string | null;
+/** Whether writing a platform's hook needs the user's explicit yes (AC-18..AC-20). */
+export declare function needsConsent(platform: LifecyclePlatform): boolean;
+/** The command that writes a consent-gated platform's hook, for every path that does not. */
+export declare function installCommand(platform: LifecyclePlatform): string;
+export interface WriteResult {
+    /** False when the file already said exactly this. */
+    written: boolean;
+    path: string;
+}
+/**
+ * Install the session-start hook, and the guard when asked, into one platform's
+ * hook file (AC-15, AC-16, AC-20). Writes the shim first when it is missing or
+ * unusable, since every command here runs through it.
+ *
+ * @throws when the guard is asked for Codex — its `PreToolUse` can deny or
+ *   rewrite a call but not ask, and the guard only ever asks.
+ */
+export declare function installLifecycleHooks(projectRoot: string, opts: {
+    platform: LifecyclePlatform;
+    guard?: boolean;
+}): WriteResult;
+/**
+ * Remove the lifecycle hooks from one platform's file, or only the guard
+ * (AC-14, AC-16). Unmarked entries and every other key stay; a file that does
+ * not exist is not created.
+ */
+export declare function removeLifecycleHooks(projectRoot: string, opts: {
+    platform: LifecyclePlatform;
+    guardOnly?: boolean;
+}): WriteResult;
+/** Whether one lifecycle hook is declared in a platform's file. Never throws. */
+export declare function lifecycleHookInstalled(projectRoot: string, platform: LifecyclePlatform, which: LifecycleHook): boolean;
+/** The line every Codex install prints: the hook is inert until the user trusts it. */
+export declare const CODEX_TRUST_STEP: string;
+/** The command that adds the Codex hook, for every path that does not write it. */
+export declare const CODEX_INSTALL_COMMAND: string;
+//# sourceMappingURL=install.d.ts.map

package/dist/hooks/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../src/hooks/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAQH,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG,OAAO,CAAC;AACxD,MAAM,MAAM,aAAa,GAAG,eAAe,GAAG,OAAO,CAAC;AAEtD,eAAO,MAAM,mBAAmB,EAAE,SAAS,iBAAiB,EAA6B,CAAC;AAC1F,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAC7D,eAAO,MAAM,aAAa,sCAAsC,CAAC;AAuBjE;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,GAAE,iBAAiC,GAAG,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAM5G;AAkCD,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,GAAG,MAAM,CAErF;AAED,+DAA+D;AAC/D,wBAAgB,aAAa,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAElE;AAED,+EAA+E;AAC/E,wBAAgB,SAAS,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,GAAG,IAAI,CAEpE;AAED,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAEjE;AAED,6FAA6F;AAC7F,wBAAgB,cAAc,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,CAElE;AAgED,MAAM,WAAW,WAAW;IAC1B,qDAAqD;IACrD,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,QAAQ,EAAE,iBAAiB,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GACrD,WAAW,CAUb;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,QAAQ,EAAE,iBAAiB,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GACzD,WAAW,CAoBb;AAED,iFAAiF;AACjF,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,EAAE,aAAa,GACnB,OAAO,CAOT;AAED,uFAAuF;AACvF,eAAO,MAAM,gBAAgB,EAAqC,MAAM,CAAC;AAEzE,mFAAmF;AACnF,eAAO,MAAM,qBAAqB,QAA0B,CAAC"}

package/dist/hooks/install.js

@@ -0,0 +1,207 @@
+/**
+ * Installs the lifecycle hooks: the session-start hook for Claude Code and
+ * Codex, and the opt-in phase guard for Claude Code
+ * (hooks-carry-lifecycle-state/AC-14..AC-16, AC-20, AC-21).
+ *
+ * Identity is a trailing marker, as for the cost hooks, but a different one
+ * (design D9). With a shared marker `aidlc cost hooks status` would count a
+ * lifecycle hook as a cost hook and `cost hooks remove` would delete it. The cost
+ * installer matches `endsWith('#aidlc-cost-hook')`, which no command here
+ * satisfies, so neither installer sees the other's entries and the cost code is
+ * unchanged. The merge below is written again rather than generalised out of
+ * `cost/hooks/claude-code.ts` because it also writes Codex's file, and the cost
+ * installer's tests pin its exact behaviour.
+ *
+ * Codex trusts a hook by its content hash, and only the user's own config may
+ * record that hash (knowledge: `codex-hook-trust-model`). So this module writes
+ * the project's `.codex/hooks.json` and nothing else for Codex — never
+ * `~/.codex/`, never a trust hash — and writes only when the text would change,
+ * so installing twice cannot cost the user the trust they already gave.
+ *
+ * Design: design.md C4
+ *
+ * @module
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { cliEntryPath } from '../cost/hooks/entry.js';
+import { shimInvocation, shimProblem, writeShim } from '../cost/hooks/shim.js';
+export const LIFECYCLE_PLATFORMS = ['claude-code', 'codex'];
+export const LIFECYCLE_HOOK_MARKER = '#aidlc-lifecycle-hook';
+export const GUARD_MATCHER = 'Edit|Write|MultiEdit|NotebookEdit';
+/** A hook needs only to start the CLI and read a few files; ten seconds is generous. */
+const TIMEOUT_SECONDS = 10;
+const EVENT = { 'session-start': 'SessionStart', guard: 'PreToolUse' };
+/**
+ * The two hook commands for a platform. Both run through the cost-capture shim,
+ * which finds an absolute `node` and this project's CLI at run time and never
+ * consults `PATH` (cost-capture-goes-dark/AC-15) — a bare `aidlc` here would be a
+ * `PATH` lookup on every session start (design D1).
+ */
+export function lifecycleCommands(platform = 'claude-code') {
+    const base = shimInvocation(PLATFORM_HOOKS[platform].rootVar);
+    return {
+        'session-start': `${base} hook session-start ${LIFECYCLE_HOOK_MARKER}`,
+        guard: `${base} hook guard ${LIFECYCLE_HOOK_MARKER}`,
+    };
+}
+/** The one table mapping a platform to its lifecycle hooks (agent-portability/AC-41). */
+const PLATFORM_HOOKS = {
+    'claude-code': { file: ['.claude', 'settings.json'], guard: true, trustStep: null, rootVar: 'CLAUDE_PROJECT_DIR' },
+    // Codex's PreToolUse can deny or rewrite a call but not ask (design D7), and a
+    // project hook runs only once the user trusts it by hash.
+    codex: {
+        file: ['.codex', 'hooks.json'],
+        guard: false,
+        trustStep: 'Codex runs it only after you trust it: open Codex in this project and run /hooks.',
+        rootVar: 'AIDLC_PROJECT_ROOT',
+    },
+};
+export function hookFilePath(projectRoot, platform) {
+    return join(projectRoot, ...PLATFORM_HOOKS[platform].file);
+}
+/** Whether the phase guard can be installed for a platform. */
+export function supportsGuard(platform) {
+    return PLATFORM_HOOKS[platform].guard;
+}
+/** The step the user still owes before the platform runs the hook, or null. */
+export function trustStep(platform) {
+    return PLATFORM_HOOKS[platform].trustStep;
+}
+/** Whether writing a platform's hook needs the user's explicit yes (AC-18..AC-20). */
+export function needsConsent(platform) {
+    return trustStep(platform) !== null;
+}
+/** The command that writes a consent-gated platform's hook, for every path that does not. */
+export function installCommand(platform) {
+    return `aidlc hook install --platform ${platform}`;
+}
+function isMarked(h) {
+    return typeof h.command === 'string' && h.command.endsWith(LIFECYCLE_HOOK_MARKER);
+}
+function groupFor(which, platform) {
+    const hook = { type: 'command', command: lifecycleCommands(platform)[which], timeout: TIMEOUT_SECONDS };
+    // No matcher on SessionStart, so it fires on startup, resume, clear and compact.
+    return which === 'guard' ? { matcher: GUARD_MATCHER, hooks: [hook] } : { hooks: [hook] };
+}
+function load(path) {
+    if (!existsSync(path))
+        return { raw: null, file: {} };
+    const raw = readFileSync(path, 'utf8');
+    // A file that does not parse is left alone: overwriting it would discard
+    // whatever the user had there. The error reaches the caller.
+    return { raw, file: JSON.parse(raw) };
+}
+function save(path, raw, file) {
+    const text = JSON.stringify(file, null, 2) + '\n';
+    if (text === raw)
+        return false;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, text);
+    return true;
+}
+/**
+ * The event's groups with every marked command taken out, and how many were.
+ * Only a group this takes a command from is dropped for being left empty; a
+ * user's group is passed through as it was, empty or not.
+ */
+function withoutMarked(groups) {
+    let removed = 0;
+    const kept = [];
+    for (const g of groups ?? []) {
+        const hooks = Array.isArray(g.hooks) ? g.hooks : [];
+        const unmarked = hooks.filter((h) => !isMarked(h));
+        removed += hooks.length - unmarked.length;
+        if (unmarked.length === hooks.length)
+            kept.push(g);
+        else if (unmarked.length > 0)
+            kept.push({ ...g, hooks: unmarked });
+    }
+    return { groups: kept, removed };
+}
+/** Exactly one marked command under the event, in the group shape the installer writes. */
+function isCurrent(groups, which, platform) {
+    const expected = groupFor(which, platform);
+    const marked = (groups ?? []).filter((g) => (g.hooks ?? []).some(isMarked));
+    return marked.length === 1 && JSON.stringify(marked[0]) === JSON.stringify(expected);
+}
+function ensure(file, which, platform) {
+    const hooks = file.hooks ?? {};
+    const event = EVENT[which];
+    // Left where it is when already current, so a re-install does not even reorder
+    // the file (AC-16).
+    if (!isCurrent(hooks[event], which, platform)) {
+        hooks[event] = [...withoutMarked(hooks[event]).groups, groupFor(which, platform)];
+    }
+    file.hooks = hooks;
+}
+/**
+ * Install the session-start hook, and the guard when asked, into one platform's
+ * hook file (AC-15, AC-16, AC-20). Writes the shim first when it is missing or
+ * unusable, since every command here runs through it.
+ *
+ * @throws when the guard is asked for Codex — its `PreToolUse` can deny or
+ *   rewrite a call but not ask, and the guard only ever asks.
+ */
+export function installLifecycleHooks(projectRoot, opts) {
+    if (opts.guard && !supportsGuard(opts.platform)) {
+        throw new Error(`the phase guard is Claude Code only — ${opts.platform} hooks can deny or rewrite a call, not ask`);
+    }
+    const path = hookFilePath(projectRoot, opts.platform);
+    const { raw, file } = load(path);
+    if (shimProblem(projectRoot) !== null)
+        writeShim(projectRoot, process.execPath, cliEntryPath());
+    ensure(file, 'session-start', opts.platform);
+    if (opts.guard)
+        ensure(file, 'guard', opts.platform);
+    return { written: save(path, raw, file), path };
+}
+/**
+ * Remove the lifecycle hooks from one platform's file, or only the guard
+ * (AC-14, AC-16). Unmarked entries and every other key stay; a file that does
+ * not exist is not created.
+ */
+export function removeLifecycleHooks(projectRoot, opts) {
+    const path = hookFilePath(projectRoot, opts.platform);
+    if (!existsSync(path))
+        return { written: false, path };
+    const { raw, file } = load(path);
+    if (!file.hooks)
+        return { written: false, path };
+    const events = opts.guardOnly ? [EVENT.guard] : Object.keys(file.hooks);
+    let removed = 0;
+    for (const event of events) {
+        if (!(event in file.hooks))
+            continue;
+        const result = withoutMarked(file.hooks[event]);
+        if (result.removed === 0)
+            continue;
+        removed += result.removed;
+        if (result.groups.length > 0)
+            file.hooks[event] = result.groups;
+        else
+            delete file.hooks[event];
+    }
+    // Nothing marked, nothing written: re-serialising would reformat a file this
+    // command had no business touching, and report a removal that did not happen.
+    if (removed === 0)
+        return { written: false, path };
+    if (Object.keys(file.hooks).length === 0)
+        delete file.hooks;
+    return { written: save(path, raw, file), path };
+}
+/** Whether one lifecycle hook is declared in a platform's file. Never throws. */
+export function lifecycleHookInstalled(projectRoot, platform, which) {
+    try {
+        const { file } = load(hookFilePath(projectRoot, platform));
+        return (file.hooks?.[EVENT[which]] ?? []).some((g) => (g.hooks ?? []).some(isMarked));
+    }
+    catch {
+        return false;
+    }
+}
+/** The line every Codex install prints: the hook is inert until the user trusts it. */
+export const CODEX_TRUST_STEP = PLATFORM_HOOKS.codex.trustStep;
+/** The command that adds the Codex hook, for every path that does not write it. */
+export const CODEX_INSTALL_COMMAND = installCommand('codex');
+//# sourceMappingURL=install.js.map

package/dist/hooks/install.js.map

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

package/dist/hooks/lifecycle-context.d.ts

@@ -0,0 +1,65 @@
+/**
+ * What a harness hook needs to know about the lifecycle: which instance is
+ * claimed in this checkout, what phase it is in, and what comes next.
+ *
+ * Read-only by contract (hooks-carry-lifecycle-state/AC-8). Everything here runs
+ * inside a `SessionStart` or `PreToolUse` hook, on every session start or every
+ * edit, so it reads only the claims and the claimed instances' own files — never
+ * every instance, ledger or cache. `aidlc status --json` reads all of those and
+ * took 3.5 s on this repository; the CLI itself starts in 0.16 s (AC-10).
+ *
+ * Requirements: hooks-carry-lifecycle-state/AC-1..AC-9
+ * Design: design.md C2
+ *
+ * @module
+ */
+import type { NextStep } from '../core/types.js';
+/** Phases in which code is not yet written — what the phase guard asks about. */
+export declare const PLANNING_PHASES: readonly string[];
+/** Longest line either hook prints (AC-9). */
+export declare const MAX_LINE = 200;
+export interface InstanceContext {
+    name: string;
+    template: string;
+    scope: string;
+    /** `current_phase` from instance.yaml — what `aidlc status --json` reports (AC-2). */
+    phase: string;
+    /** What `aidlc continue --json` reports as `nextStep` (AC-2). */
+    step: NextStep;
+    /** The lowest-numbered open task, in implementation only (AC-3). */
+    openTask: {
+        id: number;
+        title: string;
+    } | null;
+}
+/**
+ * Instances claimed in this checkout, sorted by name (AC-6).
+ *
+ * Held here means recorded from this working directory: the claim's
+ * `worktree_path` is this checkout, or it has none and this is the primary
+ * checkout. Staleness is deliberately not consulted — claims renew only at phase
+ * transitions, and one phase routinely outlasts the 60-minute window, so a
+ * live-only rule would go quiet on a compaction deep into implementation, the
+ * case this hook exists for (design D3). Session ids are not compared either:
+ * they change across `startup`.
+ */
+export declare function claimsHere(projectRoot: string): string[];
+/** `current_phase` of one instance, or null when its state cannot be read. */
+export declare function currentPhase(projectRoot: string, name: string): string | null;
+/**
+ * One instance's phase and next step, or null when any of its state cannot be
+ * read (AC-7) — a hook must never stop a session starting.
+ */
+export declare function instanceContext(projectRoot: string, name: string): InstanceContext | null;
+/**
+ * One printable line: control characters (escape codes included) become spaces,
+ * and anything past `max` is cut with an ellipsis (AC-9).
+ */
+export declare function plainLine(text: string, max?: number): string;
+/**
+ * What `aidlc hook session-start` prints: three lines for one claim, one line
+ * for several, nothing for none (AC-1, AC-4, AC-5). An instance whose state
+ * cannot be read is left out (AC-7).
+ */
+export declare function sessionStartLines(projectRoot: string): string[];
+//# sourceMappingURL=lifecycle-context.d.ts.map

package/dist/hooks/lifecycle-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-context.d.ts","sourceRoot":"","sources":["../../src/hooks/lifecycle-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,OAAO,KAAK,EAAiB,QAAQ,EAAgC,MAAM,kBAAkB,CAAC;AAQ9F,iFAAiF;AACjF,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAA2C,CAAC;AAEzF,8CAA8C;AAC9C,eAAO,MAAM,QAAQ,MAAM,CAAC;AAE5B,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,sFAAsF;IACtF,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,IAAI,EAAE,QAAQ,CAAC;IACf,oEAAoE;IACpE,QAAQ,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAChD;AAUD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAcxD;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAO7E;AAiCD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAmBzF;AAcD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,SAAW,GAAG,MAAM,CAG9D;AAmDD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAO/D"}