@pleri/olam-cli 0.1.152 → 0.1.157

package/dist/lib/k8s-secret-render.d.ts

@@ -0,0 +1,139 @@
+/**
+ * k8s-secret-render.ts — render `REPLACE_ME_FROM_*` placeholders in the
+ * shipped k8s Secret templates with real values, and persist the rendered
+ * set so reapply is idempotent.
+ *
+ * B5 of olam-issue-npm-only-k3s (npm-only operator bootstrap completion).
+ *
+ * The templates at `packages/host-cp/k8s/templates/*-secret-template.yaml`
+ * carry placeholders like `REPLACE_ME_FROM_HOME_DOTOLAM_AUTH_SECRET`. The
+ * source-of-truth value for each placeholder is documented in the template
+ * comment block; it's either a host-side file in `~/.olam/` (the compose
+ * bootstrap path) or a subprocess output (e.g. `gh auth token`).
+ *
+ * Source resolution per placeholder:
+ *
+ *   placeholder                                              → source
+ *   REPLACE_ME_FROM_HOME_DOTOLAM_AUTH_SECRET                  → file ~/.olam/auth-secret           (generate if missing)
+ *   REPLACE_ME_FROM_GH_AUTH_TOKEN                             → subprocess `gh auth token`         (warn + skip if absent)
+ *   REPLACE_ME_FROM_HOME_DOTOLAM_AUTH_DB_SECRET               → file ~/.olam/auth-db-secret        (generate if missing)
+ *   REPLACE_ME_FROM_HOME_DOTOLAM_MCP_AUTH_JWT_SECRET          → file ~/.olam/mcp-auth-jwt-secret   (generate if missing)
+ *   REPLACE_ME_FROM_HOME_DOTOLAM_KG_BEARER_TOKEN              → file ~/.olam/kg-bearer-token       (generate if missing)
+ *   REPLACE_ME_FROM_HOME_DOTOLAM_MEMORY_BEARER_SECRET         → file ~/.olam/memory-bearer-secret  (generate if missing)
+ *
+ * State persistence: `~/.olam/k8s-secrets-state.json` records the rendered
+ * Secret set so re-runs (idempotent reapply) reuse the same values. Without
+ * the state file every `olam upgrade` would rotate tokens silently, breaking
+ * worlds that have cached the previous value. Operator opts in to rotation
+ * via `--rotate-secrets`.
+ *
+ * D20 stdin-safe design: rendered YAML is built in-process and applied via
+ * stdin to `kubectl apply -f -`. Placeholder values are NEVER inlined into
+ * subprocess argv (audit:auth-callers + general security hygiene).
+ */
+export declare const K8S_SECRETS_STATE_PATH: string;
+/**
+ * One template's placeholder set + the per-host-file source it reads from.
+ * Hardcoded mapping — every secret template's `# Source:` comment names the
+ * file; the audit:cli-bundle-k8s gate ensures the templates stay in sync.
+ */
+export interface SecretTemplateBinding {
+    readonly secretName: string;
+    readonly templateRelPath: string;
+    readonly placeholders: ReadonlyArray<{
+        readonly placeholder: string;
+        readonly key: string;
+        readonly source: {
+            readonly kind: 'file';
+            readonly hostFile: string;
+        } | {
+            readonly kind: 'gh-token';
+        };
+    }>;
+}
+/** Canonical mapping for the 5 secret templates that ship with the CLI. */
+export declare const SECRET_TEMPLATE_BINDINGS: ReadonlyArray<SecretTemplateBinding>;
+/** Per-secret state record — keys map to RENDERED values reused on re-apply. */
+export interface RenderedSecret {
+    readonly keys: Record<string, string>;
+    readonly skipped?: ReadonlyArray<string>;
+}
+/** State file shape. version=1 lets us migrate the schema without breaking older state. */
+export interface K8sSecretsState {
+    readonly version: 1;
+    readonly context: string;
+    readonly namespace: string;
+    readonly generatedAt: string;
+    readonly secrets: Record<string, RenderedSecret>;
+}
+/** Injectable deps so tests don't touch the real filesystem / shell. */
+export interface RenderDeps {
+    readonly olamHome?: string;
+    readonly statePath?: string;
+    readonly readFile?: (path: string, enc: 'utf8') => string;
+    readonly writeFile?: (path: string, data: string, mode: number) => void;
+    readonly fileExists?: (path: string) => boolean;
+    readonly genRandomHex?: () => string;
+    readonly runGhTokenCmd?: () => {
+        ok: boolean;
+        token: string;
+    };
+    readonly readState?: () => K8sSecretsState | null;
+    readonly writeState?: (state: K8sSecretsState) => void;
+    readonly stderr?: NodeJS.WritableStream;
+}
+/**
+ * Read the state file. Returns null when missing OR when the version doesn't match (forward-compat).
+ */
+export declare function readSecretsState(statePath?: string): K8sSecretsState | null;
+/** Atomically write the state file (0600). */
+export declare function writeSecretsState(state: K8sSecretsState, statePath?: string): void;
+/**
+ * Result of rendering one Secret. Either:
+ *   - resolved: every placeholder got a value (rendered YAML is ready to apply).
+ *   - skipped:  at least one source was unavailable AND not generatable (e.g.
+ *               gh auth token absent); the operator must apply this secret
+ *               manually OR install gh + retry.
+ */
+export interface RenderResult {
+    readonly secretName: string;
+    readonly status: 'resolved' | 'skipped';
+    readonly renderedYaml?: string;
+    readonly keys: Record<string, string>;
+    readonly missingSources: ReadonlyArray<string>;
+}
+/**
+ * Substitute the placeholder strings in the template YAML with real values.
+ * Builds a fresh Secret YAML string (does NOT touch the template on disk).
+ *
+ * The templates hold ONE placeholder per stringData key; literal string
+ * substitution suffices. We avoid YAML parsing to keep the template comment
+ * block (which carries operator-facing documentation) intact in the rendered
+ * output.
+ */
+export declare function substitutePlaceholders(templateYaml: string, values: Record<string, string>): string;
+/**
+ * Render ONE secret template. Reads the template YAML from `templatesRoot`
+ * (resolved by the caller to either source or install-mode location),
+ * resolves each placeholder, persists generated values to host files,
+ * substitutes, and returns the rendered YAML.
+ *
+ * `reuse` carries the prior state's per-key values when an unrotated
+ * re-apply is requested; null means "this is the first apply or operator
+ * asked for rotation."
+ */
+export declare function renderOneSecret(binding: SecretTemplateBinding, templatesRoot: string, reuse: RenderedSecret | null, deps?: RenderDeps, rotate?: boolean): RenderResult;
+/**
+ * Render the full set of shipped Secret templates. `rotate=true` discards
+ * the on-disk state and regenerates every value; `rotate=false` reuses
+ * state for unchanged secrets so worlds caching old tokens don't break.
+ */
+export declare function renderAllSecrets(templatesRoot: string, opts: {
+    rotate: boolean;
+    context: string;
+    namespace: string;
+}, deps?: RenderDeps): {
+    results: ReadonlyArray<RenderResult>;
+    nextState: K8sSecretsState;
+};
+//# sourceMappingURL=k8s-secret-render.d.ts.map

package/dist/lib/k8s-secret-render.d.ts.map

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

package/dist/lib/k8s-secret-render.js

@@ -0,0 +1,281 @@
+/**
+ * k8s-secret-render.ts — render `REPLACE_ME_FROM_*` placeholders in the
+ * shipped k8s Secret templates with real values, and persist the rendered
+ * set so reapply is idempotent.
+ *
+ * B5 of olam-issue-npm-only-k3s (npm-only operator bootstrap completion).
+ *
+ * The templates at `packages/host-cp/k8s/templates/*-secret-template.yaml`
+ * carry placeholders like `REPLACE_ME_FROM_HOME_DOTOLAM_AUTH_SECRET`. The
+ * source-of-truth value for each placeholder is documented in the template
+ * comment block; it's either a host-side file in `~/.olam/` (the compose
+ * bootstrap path) or a subprocess output (e.g. `gh auth token`).
+ *
+ * Source resolution per placeholder:
+ *
+ *   placeholder                                              → source
+ *   REPLACE_ME_FROM_HOME_DOTOLAM_AUTH_SECRET                  → file ~/.olam/auth-secret           (generate if missing)
+ *   REPLACE_ME_FROM_GH_AUTH_TOKEN                             → subprocess `gh auth token`         (warn + skip if absent)
+ *   REPLACE_ME_FROM_HOME_DOTOLAM_AUTH_DB_SECRET               → file ~/.olam/auth-db-secret        (generate if missing)
+ *   REPLACE_ME_FROM_HOME_DOTOLAM_MCP_AUTH_JWT_SECRET          → file ~/.olam/mcp-auth-jwt-secret   (generate if missing)
+ *   REPLACE_ME_FROM_HOME_DOTOLAM_KG_BEARER_TOKEN              → file ~/.olam/kg-bearer-token       (generate if missing)
+ *   REPLACE_ME_FROM_HOME_DOTOLAM_MEMORY_BEARER_SECRET         → file ~/.olam/memory-bearer-secret  (generate if missing)
+ *
+ * State persistence: `~/.olam/k8s-secrets-state.json` records the rendered
+ * Secret set so re-runs (idempotent reapply) reuse the same values. Without
+ * the state file every `olam upgrade` would rotate tokens silently, breaking
+ * worlds that have cached the previous value. Operator opts in to rotation
+ * via `--rotate-secrets`.
+ *
+ * D20 stdin-safe design: rendered YAML is built in-process and applied via
+ * stdin to `kubectl apply -f -`. Placeholder values are NEVER inlined into
+ * subprocess argv (audit:auth-callers + general security hygiene).
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, statSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { OLAM_HOME } from './config.js';
+export const K8S_SECRETS_STATE_PATH = join(OLAM_HOME, 'k8s-secrets-state.json');
+const SECRET_HEX_BYTES = 32; // 64-char hex tokens — mirrors memory-secret.ts SECRET_LEN_BYTES.
+/** Canonical mapping for the 5 secret templates that ship with the CLI. */
+export const SECRET_TEMPLATE_BINDINGS = [
+    {
+        secretName: 'olam-host-cp-secret',
+        templateRelPath: 'templates/40-secret-template.yaml',
+        placeholders: [
+            {
+                placeholder: 'REPLACE_ME_FROM_HOME_DOTOLAM_AUTH_SECRET',
+                key: 'OLAM_AUTH_SECRET',
+                source: { kind: 'file', hostFile: 'auth-secret' },
+            },
+            {
+                placeholder: 'REPLACE_ME_FROM_GH_AUTH_TOKEN',
+                key: 'GH_TOKEN',
+                source: { kind: 'gh-token' },
+            },
+        ],
+    },
+    {
+        secretName: 'olam-auth-service-secret',
+        templateRelPath: 'templates/auth-service-secret-template.yaml',
+        placeholders: [
+            {
+                placeholder: 'REPLACE_ME_FROM_HOME_DOTOLAM_AUTH_DB_SECRET',
+                key: 'OLAM_AUTH_DB_SECRET',
+                source: { kind: 'file', hostFile: 'auth-db-secret' },
+            },
+        ],
+    },
+    {
+        secretName: 'olam-mcp-auth-service-secret',
+        templateRelPath: 'templates/mcp-auth-service-secret-template.yaml',
+        placeholders: [
+            {
+                placeholder: 'REPLACE_ME_FROM_HOME_DOTOLAM_MCP_AUTH_JWT_SECRET',
+                key: 'OLAM_MCP_AUTH_JWT_SECRET',
+                source: { kind: 'file', hostFile: 'mcp-auth-jwt-secret' },
+            },
+        ],
+    },
+    {
+        secretName: 'olam-kg-service-secret',
+        templateRelPath: 'templates/kg-service-secret-template.yaml',
+        placeholders: [
+            {
+                placeholder: 'REPLACE_ME_FROM_HOME_DOTOLAM_KG_BEARER_TOKEN',
+                key: 'OLAM_KG_BEARER_TOKEN',
+                source: { kind: 'file', hostFile: 'kg-bearer-token' },
+            },
+        ],
+    },
+    {
+        secretName: 'olam-memory-service-secret',
+        templateRelPath: 'templates/memory-service-secret-template.yaml',
+        placeholders: [
+            {
+                placeholder: 'REPLACE_ME_FROM_HOME_DOTOLAM_MEMORY_BEARER_SECRET',
+                key: 'OLAM_MEMORY_BEARER_SECRET',
+                source: { kind: 'file', hostFile: 'memory-bearer-secret' },
+            },
+        ],
+    },
+];
+const defaultGenRandomHex = () => randomBytes(SECRET_HEX_BYTES).toString('hex');
+const defaultRunGhTokenCmd = () => {
+    const r = spawnSync('gh', ['auth', 'token'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    if (r.status === 0 && r.stdout.trim().length > 0) {
+        return { ok: true, token: r.stdout.trim() };
+    }
+    return { ok: false, token: '' };
+};
+const defaultReadFile = (p, enc) => readFileSync(p, enc);
+const defaultWriteFile = (p, data, mode) => {
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, data, { encoding: 'utf8', mode });
+    // writeFileSync's mode is umask-respecting; chmod explicitly to be safe.
+    chmodSync(p, mode);
+};
+const defaultFileExists = (p) => existsSync(p);
+/**
+ * Read the state file. Returns null when missing OR when the version doesn't match (forward-compat).
+ */
+export function readSecretsState(statePath = K8S_SECRETS_STATE_PATH) {
+    if (!existsSync(statePath))
+        return null;
+    try {
+        const raw = readFileSync(statePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed.version !== 1)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Atomically write the state file (0600). */
+export function writeSecretsState(state, statePath = K8S_SECRETS_STATE_PATH) {
+    mkdirSync(dirname(statePath), { recursive: true });
+    const tmp = `${statePath}.tmp.${process.pid}`;
+    writeFileSync(tmp, JSON.stringify(state, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    // renameSync is atomic on POSIX
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    require('node:fs').renameSync(tmp, statePath);
+}
+/**
+ * Resolve a single placeholder's value. Returns null when the source is
+ * absent AND not generatable (gh-token only). For file-sourced placeholders
+ * we always generate if missing — that's the npm-only operator path.
+ */
+function resolveSourceValue(source, olamHome, reuseFromState, rotate, deps) {
+    if (!rotate && reuseFromState !== undefined && reuseFromState !== '') {
+        return { ok: true, value: reuseFromState };
+    }
+    if (source.kind === 'file') {
+        const filePath = join(olamHome, source.hostFile);
+        // Rotation: always generate fresh value, overwrite the host file.
+        if (rotate) {
+            const fresh = deps.genRandomHex();
+            deps.writeFile(filePath, fresh, 0o600);
+            return { ok: true, value: fresh };
+        }
+        if (deps.fileExists(filePath)) {
+            const value = deps.readFile(filePath, 'utf8').trim();
+            if (value.length > 0)
+                return { ok: true, value };
+        }
+        // Missing or empty — generate, persist, return.
+        const fresh = deps.genRandomHex();
+        deps.writeFile(filePath, fresh, 0o600);
+        return { ok: true, value: fresh };
+    }
+    // kind === 'gh-token' — not generatable; warn + skip if absent.
+    // Rotation reads gh CLI again (gh manages its own session rotation).
+    const r = deps.runGhTokenCmd();
+    if (r.ok)
+        return { ok: true, value: r.token };
+    return { ok: false, reason: 'gh CLI not authenticated; run `gh auth login` then re-run' };
+}
+/**
+ * Substitute the placeholder strings in the template YAML with real values.
+ * Builds a fresh Secret YAML string (does NOT touch the template on disk).
+ *
+ * The templates hold ONE placeholder per stringData key; literal string
+ * substitution suffices. We avoid YAML parsing to keep the template comment
+ * block (which carries operator-facing documentation) intact in the rendered
+ * output.
+ */
+export function substitutePlaceholders(templateYaml, values) {
+    let out = templateYaml;
+    for (const [placeholder, value] of Object.entries(values)) {
+        // Use split/join rather than .replace to avoid regex escaping pitfalls.
+        out = out.split(`"${placeholder}"`).join(`"${value}"`);
+    }
+    return out;
+}
+/**
+ * Render ONE secret template. Reads the template YAML from `templatesRoot`
+ * (resolved by the caller to either source or install-mode location),
+ * resolves each placeholder, persists generated values to host files,
+ * substitutes, and returns the rendered YAML.
+ *
+ * `reuse` carries the prior state's per-key values when an unrotated
+ * re-apply is requested; null means "this is the first apply or operator
+ * asked for rotation."
+ */
+export function renderOneSecret(binding, templatesRoot, reuse, deps = {}, rotate = false) {
+    const olamHome = deps.olamHome ?? OLAM_HOME;
+    const readFile = deps.readFile ?? defaultReadFile;
+    const writeFile = deps.writeFile ?? defaultWriteFile;
+    const fileExists = deps.fileExists ?? defaultFileExists;
+    const genRandomHex = deps.genRandomHex ?? defaultGenRandomHex;
+    const runGhTokenCmd = deps.runGhTokenCmd ?? defaultRunGhTokenCmd;
+    const templatePath = join(templatesRoot, binding.templateRelPath);
+    const templateYaml = readFile(templatePath, 'utf8');
+    const keys = {};
+    const placeholderToValue = {};
+    const missingSources = [];
+    for (const p of binding.placeholders) {
+        const resolved = resolveSourceValue(p.source, olamHome, reuse?.keys[p.key], rotate, { readFile, writeFile, fileExists, genRandomHex, runGhTokenCmd });
+        if (!resolved.ok) {
+            missingSources.push(`${p.key}: ${resolved.reason}`);
+            continue;
+        }
+        keys[p.key] = resolved.value;
+        placeholderToValue[p.placeholder] = resolved.value;
+    }
+    if (missingSources.length > 0) {
+        return {
+            secretName: binding.secretName,
+            status: 'skipped',
+            keys,
+            missingSources,
+        };
+    }
+    const renderedYaml = substitutePlaceholders(templateYaml, placeholderToValue);
+    return {
+        secretName: binding.secretName,
+        status: 'resolved',
+        renderedYaml,
+        keys,
+        missingSources: [],
+    };
+}
+/**
+ * Render the full set of shipped Secret templates. `rotate=true` discards
+ * the on-disk state and regenerates every value; `rotate=false` reuses
+ * state for unchanged secrets so worlds caching old tokens don't break.
+ */
+export function renderAllSecrets(templatesRoot, opts, deps = {}) {
+    const readState = deps.readState ?? (() => readSecretsState(deps.statePath ?? K8S_SECRETS_STATE_PATH));
+    const writeState = deps.writeState ?? ((s) => writeSecretsState(s, deps.statePath ?? K8S_SECRETS_STATE_PATH));
+    const prior = opts.rotate ? null : readState();
+    const results = [];
+    const nextSecrets = {};
+    for (const binding of SECRET_TEMPLATE_BINDINGS) {
+        const reuse = prior?.secrets[binding.secretName] ?? null;
+        const r = renderOneSecret(binding, templatesRoot, reuse, deps, opts.rotate);
+        results.push(r);
+        nextSecrets[binding.secretName] = {
+            keys: r.keys,
+            ...(r.missingSources.length > 0 ? { skipped: r.missingSources } : {}),
+        };
+    }
+    const nextState = {
+        version: 1,
+        context: opts.context,
+        namespace: opts.namespace,
+        generatedAt: new Date().toISOString(),
+        secrets: nextSecrets,
+    };
+    // Only persist when at least one secret resolved — avoids an empty state file
+    // on a wholly-failed first run (where every gh-token source was absent and
+    // the operator hadn't yet generated `~/.olam/*` files).
+    if (results.some((r) => r.status === 'resolved')) {
+        writeState(nextState);
+    }
+    return { results, nextState };
+}
+//# sourceMappingURL=k8s-secret-render.js.map

package/dist/lib/k8s-secret-render.js.map

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

package/dist/lib/kubectl-context.d.ts

@@ -0,0 +1,38 @@
+/**
+ * kubectl-context.ts — shared kubectl-context resolver.
+ *
+ * Single source of truth for the D1 / SEC-NEW-003 context-resolution
+ * policy. Extracted so `upgrade-kubernetes.ts`, `auth-refresh-kubernetes.ts`,
+ * `services.ts`, and any future kubernetes-substrate consumer can call the
+ * same helper instead of duplicating it.
+ *
+ * Policy (matches the pre-existing auth-refresh-kubernetes.ts and services.ts
+ * behaviour — see also docs/architecture/peripheral-services-on-k3s.md):
+ *
+ *   1. `host.kubectl_context_pinned` in `~/.olam/config.json` (preferred,
+ *      persistent — the doc-recommended way).
+ *   2. `OLAM_K8S_CONTEXT_ACK` env var (deprecated fallback; emits a
+ *      deprecation warning to nudge operators toward (1)).
+ *   3. Both absent → error result with actionable remediation.
+ *
+ * No `fs` reads in this module beyond what `readConfig` does; no kubectl
+ * invocations. Pure resolution. Safe to call from any layer.
+ */
+/**
+ * Result shape mirrors `auth-refresh-kubernetes.ts`'s pre-existing public
+ * `resolveKubectlContext` so callers there can be migrated without source
+ * changes. Exactly one of `context` or `error` is set.
+ */
+export interface KubectlContextResolution {
+    readonly context?: string;
+    readonly deprecationWarning?: string;
+    readonly error?: string;
+}
+/**
+ * Resolve the operator's kubectl context name. See module docstring for policy.
+ *
+ * `configPath` lets callers (and tests) point at a non-default config file.
+ * Returns a `KubectlContextResolution` — callers branch on `error` vs `context`.
+ */
+export declare function resolveKubectlContext(configPath?: string): KubectlContextResolution;
+//# sourceMappingURL=kubectl-context.d.ts.map

package/dist/lib/kubectl-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kubectl-context.d.ts","sourceRoot":"","sources":["../../src/lib/kubectl-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AASD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,wBAAwB,CAcnF"}

package/dist/lib/kubectl-context.js

@@ -0,0 +1,43 @@
+/**
+ * kubectl-context.ts — shared kubectl-context resolver.
+ *
+ * Single source of truth for the D1 / SEC-NEW-003 context-resolution
+ * policy. Extracted so `upgrade-kubernetes.ts`, `auth-refresh-kubernetes.ts`,
+ * `services.ts`, and any future kubernetes-substrate consumer can call the
+ * same helper instead of duplicating it.
+ *
+ * Policy (matches the pre-existing auth-refresh-kubernetes.ts and services.ts
+ * behaviour — see also docs/architecture/peripheral-services-on-k3s.md):
+ *
+ *   1. `host.kubectl_context_pinned` in `~/.olam/config.json` (preferred,
+ *      persistent — the doc-recommended way).
+ *   2. `OLAM_K8S_CONTEXT_ACK` env var (deprecated fallback; emits a
+ *      deprecation warning to nudge operators toward (1)).
+ *   3. Both absent → error result with actionable remediation.
+ *
+ * No `fs` reads in this module beyond what `readConfig` does; no kubectl
+ * invocations. Pure resolution. Safe to call from any layer.
+ */
+import { readConfig } from './config.js';
+const DEPRECATION_WARNING = 'OLAM_K8S_CONTEXT_ACK is deprecated; set host.kubectl_context_pinned in ~/.olam/config.json';
+const NO_CONTEXT_ERROR = 'kubectl_context_pinned is not set in ~/.olam/config.json and OLAM_K8S_CONTEXT_ACK is not set.\n' +
+    '  Set host.kubectl_context_pinned in ~/.olam/config.json to your kubectl context name.';
+/**
+ * Resolve the operator's kubectl context name. See module docstring for policy.
+ *
+ * `configPath` lets callers (and tests) point at a non-default config file.
+ * Returns a `KubectlContextResolution` — callers branch on `error` vs `context`.
+ */
+export function resolveKubectlContext(configPath) {
+    const cfg = readConfig({ configPath });
+    const raw = cfg.host['kubectl_context_pinned'];
+    if (typeof raw === 'string' && raw.length > 0) {
+        return { context: raw };
+    }
+    const ack = process.env['OLAM_K8S_CONTEXT_ACK'];
+    if (typeof ack === 'string' && ack.length > 0) {
+        return { context: ack, deprecationWarning: DEPRECATION_WARNING };
+    }
+    return { error: NO_CONTEXT_ERROR };
+}
+//# sourceMappingURL=kubectl-context.js.map

package/dist/lib/kubectl-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kubectl-context.js","sourceRoot":"","sources":["../../src/lib/kubectl-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAazC,MAAM,mBAAmB,GACvB,4FAA4F,CAAC;AAE/F,MAAM,gBAAgB,GACpB,iGAAiG;IACjG,wFAAwF,CAAC;AAE3F;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,UAAmB;IACvD,MAAM,GAAG,GAAG,UAAU,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC;IACvC,MAAM,GAAG,GAAI,GAAG,CAAC,IAAgC,CAAC,wBAAwB,CAAC,CAAC;IAE5E,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9C,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;IAC1B,CAAC;IAED,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;IAChD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9C,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,CAAC;IACnE,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC;AACrC,CAAC"}

package/dist/lib/memory-host-process-migration.d.ts

@@ -0,0 +1,56 @@
+/**
+ * memory-host-process-migration.ts — idempotent cleanup of the Phase A
+ * host-process model's residual state on disk.
+ *
+ * Phase A spawned `agentmemory` as a host child process and recorded its PID
+ * at `~/.olam/memory.pid` + stdout/stderr at `~/.olam/memory-service.log`.
+ * Phase B repoints `olam memory start` at the Docker substrate (this skill's
+ * `MemoryServiceContainerController`); the legacy pidfile + log become orphan
+ * artefacts the moment the new substrate runs.
+ *
+ * This helper is called from `runMemoryStart` / `runMemoryStop` (B1 / B2) BEFORE
+ * the substrate handoff so operators upgrading from the host-process model
+ * never have to manually clean up.
+ *
+ * PID-reuse defence (T2 mitigation). A stale pidfile can record a PID that
+ * the OS has since recycled to an unrelated process. SIGTERMing the wrong PID
+ * is a foot-gun. Defence:
+ *   1. If pidfile is absent → no-op.
+ *   2. If recorded PID is dead (kill(0) throws ESRCH) → unlink pidfile only.
+ *   3. If recorded PID is alive BUT `ps -p <pid> -o comm=` doesn't return
+ *      `node` (the legacy host-process was always a node child) → unlink
+ *      pidfile WITHOUT signalling. Logs a warning so support can diagnose.
+ *   4. Only when PID is alive AND comm=node → SIGTERM, wait up to 5s,
+ *      SIGKILL on timeout, then unlink.
+ *
+ * Plan reference: docs/plans/memory-service-as-docker-peripheral/phase-b-tasks.md B5
+ */
+export interface MigrationResult {
+    /** True if any legacy artefact (pidfile or log) was found + cleaned. */
+    readonly cleaned: boolean;
+    /** One-line description of what happened (for operator-visible logging). */
+    readonly summary: string;
+}
+export interface MigrationOptions {
+    /** Remove `memory-service.log` in addition to the pidfile (B2 stop path uses this). */
+    removeLog?: boolean;
+    /** Override the pidfile path. Defaults to MEMORY_PID_PATH. Used by tests. */
+    pidPath?: string;
+    /** Override the log path. Defaults to MEMORY_LOG_PATH. Used by tests. */
+    logPath?: string;
+}
+/**
+ * Detect + clean up legacy host-process state. Idempotent — safe to call on
+ * every `olam memory start` / `olam memory stop` invocation; no-op when no
+ * legacy artefacts present.
+ *
+ * Side effects (only when artefacts present):
+ *   - Unlink `~/.olam/memory.pid` if it exists.
+ *   - Send SIGTERM (then SIGKILL on timeout) to the recorded PID iff it's
+ *     alive AND its comm name is `node` (the legacy spawn shape).
+ *   - Leave `~/.olam/memory-service.log` in place by default — operators
+ *     may want to inspect it post-migration. Pass `{ removeLog: true }` to
+ *     remove it explicitly (B2's stop path uses this).
+ */
+export declare function migrateFromHostProcess(opts?: MigrationOptions): MigrationResult;
+//# sourceMappingURL=memory-host-process-migration.d.ts.map

package/dist/lib/memory-host-process-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-host-process-migration.d.ts","sourceRoot":"","sources":["../../src/lib/memory-host-process-migration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAMH,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,uFAAuF;IACvF,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,GAAE,gBAAqB,GAAG,eAAe,CAoDnF"}