chief-helm 0.1.1

package/dist/core/repo.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @file Local machine config and instance repo management.
+ *
+ * Owns the single conf store instance that backs ~/.chief/config.json,
+ * provides typed accessors for LocalConfig, and validates that the
+ * personal instance repo contains the expected CHIEF directory structure
+ * before any command reads from or writes to it.
+ *
+ * Every command that operates against the instance repo calls
+ * requireSetup() first so that missing or incomplete configuration
+ * produces a clear, actionable error rather than a crash.
+ */
+import Conf from "conf";
+import type { LocalConfig } from "../types/index.js";
+/**
+ * Singleton conf store backed by ~/.chief/config.json.
+ *
+ * The cwd override places the file at ~/.chief/ rather than the
+ * platform default config directory, matching the path specified
+ * in the HELM PRD.
+ *
+ * Access this store through the typed helpers below rather than
+ * calling store.get/set directly in command files.
+ */
+export declare const localStore: Conf<LocalConfig>;
+/**
+ * Returns the full local config object.
+ * The conf store guarantees all fields are present due to the defaults
+ * provided at initialisation.
+ */
+export declare function getLocalConfig(): LocalConfig;
+/**
+ * Applies a partial update to the local config.
+ * Only the provided keys are modified; all others are left unchanged.
+ */
+export declare function updateLocalConfig(updates: Partial<LocalConfig>): void;
+/**
+ * Asserts that helm setup has been completed successfully.
+ *
+ * Must be called at the top of every command action except `setup`
+ * itself and the root `--version` flag. Throws HelmError if setup
+ * is incomplete, directing the user to run helm setup.
+ *
+ * @throws {HelmError} When setup_complete is false or the repo path is empty.
+ */
+export declare function requireSetup(): void;
+/**
+ * Validates that the directory at repoPath is a properly initialised
+ * CHIEF instance repo by checking for required subdirectories and
+ * config files. Does not validate YAML content — only structure.
+ *
+ * @param repoPath - Absolute path to the candidate repo directory.
+ * @returns True if all required structure is present.
+ */
+export declare function isValidRepoStructure(repoPath: string): boolean;
+/**
+ * Returns the absolute path to a file or directory inside the instance
+ * repo, joining the stored repo root with the given relative segments.
+ *
+ * Requires setup to be complete. Use requireSetup() before calling this
+ * in command handlers.
+ *
+ * @param segments - Path segments relative to the repo root.
+ */
+export declare function repoPath(...segments: string[]): string;
+/**
+ * Expands a ~ prefix in a path string to the current user's home directory.
+ * Used when accepting repo paths from inquirer prompts.
+ */
+export declare function expandHomePath(inputPath: string): string;
+//# sourceMappingURL=repo.d.ts.map

package/dist/core/repo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo.d.ts","sourceRoot":"","sources":["../../src/core/repo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAgDrD;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,mBAIrB,CAAC;AAIH;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,WAAW,CAE5C;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI,CAIrE;AAID;;;;;;;;GAQG;AACH,wBAAgB,YAAY,IAAI,IAAI,CASnC;AAID;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAY9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAGtD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAKxD"}

package/dist/core/repo.js

@@ -0,0 +1,152 @@
+/**
+ * @file Local machine config and instance repo management.
+ *
+ * Owns the single conf store instance that backs ~/.chief/config.json,
+ * provides typed accessors for LocalConfig, and validates that the
+ * personal instance repo contains the expected CHIEF directory structure
+ * before any command reads from or writes to it.
+ *
+ * Every command that operates against the instance repo calls
+ * requireSetup() first so that missing or incomplete configuration
+ * produces a clear, actionable error rather than a crash.
+ */
+import os from "os";
+import path from "path";
+import fs from "fs";
+import Conf from "conf";
+import { HelmError } from "../utils/errors.js";
+// ─── Directory / File Constants ───────────────────────────────────────────────
+/**
+ * Top-level directories that must exist in a valid CHIEF instance repo.
+ * Validated during helm setup Step 1 and requireSetup().
+ */
+const REQUIRED_REPO_DIRS = [
+    "config",
+    "users",
+    "instructions",
+    "templates",
+    "context",
+    "outputs",
+    "state",
+    "logs",
+    "knowledge",
+];
+/**
+ * Config files that must exist under /config/ in the instance repo.
+ * If these are absent the repo is not a properly initialised CHIEF instance.
+ */
+const REQUIRED_CONFIG_FILES = [
+    "inputs.yaml",
+    "agents.yaml",
+    "flows.yaml",
+    "triggers.yaml",
+];
+// ─── Conf Store ───────────────────────────────────────────────────────────────
+/**
+ * Default values written to ~/.chief/config.json on first access.
+ * All fields must be present so TypeScript can infer the full LocalConfig
+ * shape without optional markers on the conf store generic.
+ */
+const LOCAL_CONFIG_DEFAULTS = {
+    instance_repo_path: "",
+    active_user: "",
+    editor: process.env["EDITOR"] ?? "code",
+    setup_complete: false,
+    last_sync: "",
+    secrets_manifest: [],
+};
+/**
+ * Singleton conf store backed by ~/.chief/config.json.
+ *
+ * The cwd override places the file at ~/.chief/ rather than the
+ * platform default config directory, matching the path specified
+ * in the HELM PRD.
+ *
+ * Access this store through the typed helpers below rather than
+ * calling store.get/set directly in command files.
+ */
+export const localStore = new Conf({
+    projectName: "chief",
+    cwd: path.join(os.homedir(), ".chief"),
+    defaults: LOCAL_CONFIG_DEFAULTS,
+});
+// ─── Typed Accessors ──────────────────────────────────────────────────────────
+/**
+ * Returns the full local config object.
+ * The conf store guarantees all fields are present due to the defaults
+ * provided at initialisation.
+ */
+export function getLocalConfig() {
+    return localStore.store;
+}
+/**
+ * Applies a partial update to the local config.
+ * Only the provided keys are modified; all others are left unchanged.
+ */
+export function updateLocalConfig(updates) {
+    for (const [key, value] of Object.entries(updates)) {
+        localStore.set(key, value);
+    }
+}
+// ─── Setup Guard ──────────────────────────────────────────────────────────────
+/**
+ * Asserts that helm setup has been completed successfully.
+ *
+ * Must be called at the top of every command action except `setup`
+ * itself and the root `--version` flag. Throws HelmError if setup
+ * is incomplete, directing the user to run helm setup.
+ *
+ * @throws {HelmError} When setup_complete is false or the repo path is empty.
+ */
+export function requireSetup() {
+    const config = getLocalConfig();
+    if (!config.setup_complete || config.instance_repo_path === "") {
+        throw new HelmError("HELM has not been set up on this machine.", "Run: helm setup");
+    }
+}
+// ─── Repo Validation ──────────────────────────────────────────────────────────
+/**
+ * Validates that the directory at repoPath is a properly initialised
+ * CHIEF instance repo by checking for required subdirectories and
+ * config files. Does not validate YAML content — only structure.
+ *
+ * @param repoPath - Absolute path to the candidate repo directory.
+ * @returns True if all required structure is present.
+ */
+export function isValidRepoStructure(repoPath) {
+    if (!fs.existsSync(repoPath))
+        return false;
+    for (const dir of REQUIRED_REPO_DIRS) {
+        if (!fs.existsSync(path.join(repoPath, dir)))
+            return false;
+    }
+    for (const file of REQUIRED_CONFIG_FILES) {
+        if (!fs.existsSync(path.join(repoPath, "config", file)))
+            return false;
+    }
+    return true;
+}
+/**
+ * Returns the absolute path to a file or directory inside the instance
+ * repo, joining the stored repo root with the given relative segments.
+ *
+ * Requires setup to be complete. Use requireSetup() before calling this
+ * in command handlers.
+ *
+ * @param segments - Path segments relative to the repo root.
+ */
+export function repoPath(...segments) {
+    const root = localStore.get("instance_repo_path");
+    return path.join(root, ...segments);
+}
+/**
+ * Expands a ~ prefix in a path string to the current user's home directory.
+ * Used when accepting repo paths from inquirer prompts.
+ */
+export function expandHomePath(inputPath) {
+    if (inputPath.startsWith("~/")) {
+        return path.join(os.homedir(), inputPath.slice(2));
+    }
+    return inputPath;
+}
+//# sourceMappingURL=repo.js.map

package/dist/core/repo.js.map

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

package/dist/core/secrets.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @file OS keychain integration for HELM.
+ *
+ * All secret storage and retrieval is routed through this module.
+ * Secret values are handled as transiently as possible:
+ *
+ *   - Values are never written to any file, log, or error message.
+ *   - The only moment a value appears in memory outside this module is
+ *     during the masked inquirer prompt in the setup wizard and
+ *     helm secrets set — immediately passed to setSecret() and discarded.
+ *   - listSecretKeys() returns key names only. Values are never returned
+ *     to callers that don't explicitly call getSecret().
+ *
+ * A manifest of key names (not values) is stored in the local conf store
+ * at ~/.chief/config.json because the OS keychain API does not provide
+ * an enumeration method. The manifest is always kept in sync with the
+ * keychain by setSecret() and deleteSecret().
+ *
+ * Keychain service name: "chief"
+ * Account format: "[username]/[KEY_NAME]"
+ */
+/**
+ * Stores a secret value in the OS keychain and records the key name
+ * in the local manifest.
+ *
+ * The value is accepted as a parameter and immediately forwarded to
+ * keytar. Callers must not retain the value after this call returns.
+ *
+ * @param username - Active username (used as the account prefix).
+ * @param key      - Secret key name, e.g. "GMAIL_CLIENT_ID".
+ * @param value    - The secret value. Never logged.
+ * @throws {HelmError} If the keychain write fails.
+ */
+export declare function setSecret(username: string, key: string, value: string): Promise<void>;
+/**
+ * Retrieves a secret value from the OS keychain.
+ *
+ * Returns null if the key does not exist. Callers must handle the null
+ * case by throwing an appropriate HelmError naming the missing key and
+ * directing the user to run helm secrets set.
+ *
+ * The returned value must not be logged, printed, or included in any
+ * user-facing string.
+ *
+ * @param username - Active username.
+ * @param key      - Secret key name to retrieve.
+ * @throws {HelmError} If the keychain read fails unexpectedly.
+ */
+export declare function getSecret(username: string, key: string): Promise<string | null>;
+/**
+ * Returns the list of secret key names stored for the given username.
+ * Values are never returned — only names.
+ *
+ * Reads from the local manifest rather than querying the keychain
+ * directly, because the keychain API does not support enumeration.
+ *
+ * @param username - Active username to filter by.
+ */
+export declare function listSecretKeys(username: string): string[];
+/**
+ * Returns true if a secret with the given key name exists in the
+ * OS keychain for the given username.
+ *
+ * @param username - Active username.
+ * @param key      - Secret key name to check.
+ * @throws {HelmError} If the keychain read fails.
+ */
+export declare function verifySecret(username: string, key: string): Promise<boolean>;
+/**
+ * Removes a secret from the OS keychain and removes its name from the
+ * local manifest.
+ *
+ * @param username - Active username.
+ * @param key      - Secret key name to delete.
+ * @returns True if the key existed and was deleted; false if it did not exist.
+ * @throws {HelmError} If the keychain deletion fails.
+ */
+export declare function deleteSecret(username: string, key: string): Promise<boolean>;
+//# sourceMappingURL=secrets.d.ts.map

package/dist/core/secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../../src/core/secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAiEH;;;;;;;;;;;GAWG;AACH,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAcf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAYxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAQzD;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,OAAO,CAAC,CAGlB;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,OAAO,CAAC,CAuBlB"}

package/dist/core/secrets.js

@@ -0,0 +1,168 @@
+/**
+ * @file OS keychain integration for HELM.
+ *
+ * All secret storage and retrieval is routed through this module.
+ * Secret values are handled as transiently as possible:
+ *
+ *   - Values are never written to any file, log, or error message.
+ *   - The only moment a value appears in memory outside this module is
+ *     during the masked inquirer prompt in the setup wizard and
+ *     helm secrets set — immediately passed to setSecret() and discarded.
+ *   - listSecretKeys() returns key names only. Values are never returned
+ *     to callers that don't explicitly call getSecret().
+ *
+ * A manifest of key names (not values) is stored in the local conf store
+ * at ~/.chief/config.json because the OS keychain API does not provide
+ * an enumeration method. The manifest is always kept in sync with the
+ * keychain by setSecret() and deleteSecret().
+ *
+ * Keychain service name: "chief"
+ * Account format: "[username]/[KEY_NAME]"
+ */
+import keytar from "keytar";
+import chalk from "chalk";
+import { localStore } from "./repo.js";
+import { HelmError } from "../utils/errors.js";
+/** Service name used for all entries in the OS keychain. */
+const KEYCHAIN_SERVICE = "chief";
+// ─── Keychain Heads-Up ────────────────────────────────────────────────────────
+/**
+ * Module-level flag ensuring the macOS keychain access prompt
+ * explanation is printed only once per process invocation.
+ */
+let keychainHeadsUpShown = false;
+/**
+ * Prints a one-line notice before the first keychain operation in a
+ * process. macOS will show a native permission dialog the first time
+ * an app accesses the keychain; without this notice users may be
+ * confused or alarmed by the unexpected OS popup.
+ */
+function ensureKeychainHeadsUp() {
+    if (!keychainHeadsUpShown) {
+        process.stdout.write(chalk.dim("  ℹ  Your OS may prompt you to allow keychain access — this is expected.\n"));
+        keychainHeadsUpShown = true;
+    }
+}
+// ─── Manifest Helpers ─────────────────────────────────────────────────────────
+/**
+ * Adds a fully-qualified key name ("[username]/[KEY_NAME]") to the
+ * manifest in local config if it is not already present.
+ */
+function addToManifest(username, key) {
+    const fullKey = `${username}/${key}`;
+    const manifest = localStore.get("secrets_manifest") ?? [];
+    if (!manifest.includes(fullKey)) {
+        localStore.set("secrets_manifest", [...manifest, fullKey]);
+    }
+}
+/**
+ * Removes a fully-qualified key name from the manifest in local config.
+ * No-op if the key is not present.
+ */
+function removeFromManifest(username, key) {
+    const fullKey = `${username}/${key}`;
+    const manifest = localStore.get("secrets_manifest") ?? [];
+    localStore.set("secrets_manifest", manifest.filter((k) => k !== fullKey));
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Stores a secret value in the OS keychain and records the key name
+ * in the local manifest.
+ *
+ * The value is accepted as a parameter and immediately forwarded to
+ * keytar. Callers must not retain the value after this call returns.
+ *
+ * @param username - Active username (used as the account prefix).
+ * @param key      - Secret key name, e.g. "GMAIL_CLIENT_ID".
+ * @param value    - The secret value. Never logged.
+ * @throws {HelmError} If the keychain write fails.
+ */
+export async function setSecret(username, key, value) {
+    ensureKeychainHeadsUp();
+    try {
+        await keytar.setPassword(KEYCHAIN_SERVICE, `${username}/${key}`, value);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new HelmError(`Failed to store secret "${key}" in the OS keychain: ${detail}`, "Ensure your OS keychain is accessible and try again.");
+    }
+    addToManifest(username, key);
+}
+/**
+ * Retrieves a secret value from the OS keychain.
+ *
+ * Returns null if the key does not exist. Callers must handle the null
+ * case by throwing an appropriate HelmError naming the missing key and
+ * directing the user to run helm secrets set.
+ *
+ * The returned value must not be logged, printed, or included in any
+ * user-facing string.
+ *
+ * @param username - Active username.
+ * @param key      - Secret key name to retrieve.
+ * @throws {HelmError} If the keychain read fails unexpectedly.
+ */
+export async function getSecret(username, key) {
+    ensureKeychainHeadsUp();
+    try {
+        return await keytar.getPassword(KEYCHAIN_SERVICE, `${username}/${key}`);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new HelmError(`Failed to read secret "${key}" from the OS keychain: ${detail}`, "Ensure your OS keychain is accessible and try again.");
+    }
+}
+/**
+ * Returns the list of secret key names stored for the given username.
+ * Values are never returned — only names.
+ *
+ * Reads from the local manifest rather than querying the keychain
+ * directly, because the keychain API does not support enumeration.
+ *
+ * @param username - Active username to filter by.
+ */
+export function listSecretKeys(username) {
+    const manifest = localStore.get("secrets_manifest") ?? [];
+    const prefix = `${username}/`;
+    return manifest
+        .filter((k) => k.startsWith(prefix))
+        .map((k) => k.slice(prefix.length))
+        .sort();
+}
+/**
+ * Returns true if a secret with the given key name exists in the
+ * OS keychain for the given username.
+ *
+ * @param username - Active username.
+ * @param key      - Secret key name to check.
+ * @throws {HelmError} If the keychain read fails.
+ */
+export async function verifySecret(username, key) {
+    const value = await getSecret(username, key);
+    return value !== null;
+}
+/**
+ * Removes a secret from the OS keychain and removes its name from the
+ * local manifest.
+ *
+ * @param username - Active username.
+ * @param key      - Secret key name to delete.
+ * @returns True if the key existed and was deleted; false if it did not exist.
+ * @throws {HelmError} If the keychain deletion fails.
+ */
+export async function deleteSecret(username, key) {
+    ensureKeychainHeadsUp();
+    let deleted;
+    try {
+        deleted = await keytar.deletePassword(KEYCHAIN_SERVICE, `${username}/${key}`);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new HelmError(`Failed to delete secret "${key}" from the OS keychain: ${detail}`, "Ensure your OS keychain is accessible and try again.");
+    }
+    if (deleted) {
+        removeFromManifest(username, key);
+    }
+    return deleted;
+}
+//# sourceMappingURL=secrets.js.map

package/dist/core/secrets.js.map

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

package/dist/core/state.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @file State file I/O for the instance repo.
+ *
+ * Manages the JSON state files under state/[username]/ in the personal
+ * instance repo. These files track run history, deferred tasks, and
+ * idempotency identifiers across flow executions.
+ *
+ * State files are written by HELM after flow runs and read by helm status
+ * and helm logs. They are committed to git as part of the post-run commit.
+ */
+import type { LastRunState } from "../types/index.js";
+/**
+ * Reads state/[username]/last_run.json and returns the parsed object.
+ * Returns an empty object when the file does not yet exist (first run).
+ *
+ * @param repoRoot - Absolute path to the instance repo root.
+ * @param username - Active username.
+ */
+export declare function readLastRunState(repoRoot: string, username: string): LastRunState;
+/**
+ * Writes a complete LastRunState to state/[username]/last_run.json.
+ *
+ * @param repoRoot - Absolute path to the instance repo root.
+ * @param username - Active username.
+ * @param state    - Full state object to persist.
+ */
+export declare function writeLastRunState(repoRoot: string, username: string, state: LastRunState): void;
+/**
+ * Records the result of a single flow run into last_run.json.
+ * Reads the current state first and merges the new record.
+ *
+ * @param repoRoot - Absolute path to the instance repo root.
+ * @param username - Active username.
+ * @param flowId   - Flow identifier to update.
+ * @param status   - Terminal status of the completed run.
+ */
+export declare function recordFlowRun(repoRoot: string, username: string, flowId: string, status: "success" | "failed"): void;
+/**
+ * Ensures the state/[username]/ directory exists in the repo,
+ * creating it if absent. Called during helm setup.
+ *
+ * @param repoRoot - Absolute path to the instance repo root.
+ * @param username - Active username.
+ */
+export declare function ensureStateDir(repoRoot: string, username: string): void;
+//# sourceMappingURL=state.d.ts.map

package/dist/core/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/core/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAmEtD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,YAAY,CAId;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,YAAY,GAClB,IAAI,CAGN;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,SAAS,GAAG,QAAQ,GAC3B,IAAI,CAMN;AAID;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAKvE"}

package/dist/core/state.js

@@ -0,0 +1,119 @@
+/**
+ * @file State file I/O for the instance repo.
+ *
+ * Manages the JSON state files under state/[username]/ in the personal
+ * instance repo. These files track run history, deferred tasks, and
+ * idempotency identifiers across flow executions.
+ *
+ * State files are written by HELM after flow runs and read by helm status
+ * and helm logs. They are committed to git as part of the post-run commit.
+ */
+import fs from "fs";
+import path from "path";
+import { HelmError } from "../utils/errors.js";
+// ─── Internal Helpers ─────────────────────────────────────────────────────────
+/**
+ * Returns the absolute path to the state directory for the given user.
+ *
+ * @param repoRoot - Absolute path to the instance repo root.
+ * @param username - Active username.
+ */
+function stateDir(repoRoot, username) {
+    return path.join(repoRoot, "state", username);
+}
+/**
+ * Reads and parses a JSON state file. Returns null if the file does not
+ * exist (treated as initial state rather than an error). Throws HelmError
+ * if the file exists but cannot be parsed.
+ *
+ * @param filePath - Absolute path to the JSON file.
+ * @param label    - Human-readable name for error messages.
+ */
+function readStateFile(filePath, label) {
+    if (!fs.existsSync(filePath))
+        return null;
+    const raw = fs.readFileSync(filePath, "utf-8");
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new HelmError(`State file ${label} is corrupted: ${detail}`, `Delete or reset ${filePath} to clear the corrupt state.`);
+    }
+}
+/**
+ * Writes a value to a JSON state file, creating the parent directory
+ * if needed. Throws HelmError on write failure.
+ *
+ * @param filePath - Absolute path to write.
+ * @param data     - Value to serialise.
+ * @param label    - Human-readable name for error messages.
+ */
+function writeStateFile(filePath, data, label) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    try {
+        fs.writeFileSync(filePath, JSON.stringify(data, null, 2), "utf-8");
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new HelmError(`Failed to write state file ${label}: ${detail}`, `Check file permissions for ${filePath}.`);
+    }
+}
+// ─── Last Run State ───────────────────────────────────────────────────────────
+/**
+ * Reads state/[username]/last_run.json and returns the parsed object.
+ * Returns an empty object when the file does not yet exist (first run).
+ *
+ * @param repoRoot - Absolute path to the instance repo root.
+ * @param username - Active username.
+ */
+export function readLastRunState(repoRoot, username) {
+    const filePath = path.join(stateDir(repoRoot, username), "last_run.json");
+    const parsed = readStateFile(filePath, "last_run.json");
+    return parsed ?? {};
+}
+/**
+ * Writes a complete LastRunState to state/[username]/last_run.json.
+ *
+ * @param repoRoot - Absolute path to the instance repo root.
+ * @param username - Active username.
+ * @param state    - Full state object to persist.
+ */
+export function writeLastRunState(repoRoot, username, state) {
+    const filePath = path.join(stateDir(repoRoot, username), "last_run.json");
+    writeStateFile(filePath, state, "last_run.json");
+}
+/**
+ * Records the result of a single flow run into last_run.json.
+ * Reads the current state first and merges the new record.
+ *
+ * @param repoRoot - Absolute path to the instance repo root.
+ * @param username - Active username.
+ * @param flowId   - Flow identifier to update.
+ * @param status   - Terminal status of the completed run.
+ */
+export function recordFlowRun(repoRoot, username, flowId, status) {
+    const current = readLastRunState(repoRoot, username);
+    writeLastRunState(repoRoot, username, {
+        ...current,
+        [flowId]: { timestamp: new Date().toISOString(), status },
+    });
+}
+// ─── User State Directory Bootstrap ──────────────────────────────────────────
+/**
+ * Ensures the state/[username]/ directory exists in the repo,
+ * creating it if absent. Called during helm setup.
+ *
+ * @param repoRoot - Absolute path to the instance repo root.
+ * @param username - Active username.
+ */
+export function ensureStateDir(repoRoot, username) {
+    const dir = stateDir(repoRoot, username);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/core/state.js.map

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