@oxygen-agent/cli 1.263.0 → 1.272.83

package/dist/knowledge-mirror.d.ts

@@ -0,0 +1,106 @@
+export declare const MIRROR_LOCK_STALE_MS: number;
+export declare const MIRROR_SLUG_PATTERN: RegExp;
+export declare const GENERATED_MIRROR_FILE_HEADER = "<!-- generated by oxygen knowledge sync \u2014 local edits are overwritten -->";
+export type MirrorPageRecord = {
+    id: string;
+    revision: number;
+    /** sha256 hex of the exact bytes the server rendered and this client wrote. */
+    content_sha256: string;
+};
+export type MirrorState = {
+    api_host: string;
+    org_id: string;
+    /** Resumable sync/delta keyset cursor; null before the first completed batch. */
+    cursor: string | null;
+    /** ISO timestamp of the last fully completed sync; null = stale/never synced. */
+    last_sync_at: string | null;
+    pages: Record<string, MirrorPageRecord>;
+};
+export type MirrorIndexPage = {
+    slug: string;
+    title?: string | null;
+    type?: string | null;
+    oneLiner?: string | null;
+    tags?: string[];
+    revision?: number;
+    canonical?: boolean;
+    degree?: number;
+};
+export type MirrorIndexSnapshot = {
+    pages: MirrorIndexPage[];
+    counts?: {
+        total?: number;
+        byType?: Record<string, number>;
+        byStatus?: Record<string, number>;
+    };
+};
+export type MirrorLogEntry = {
+    seq?: string;
+    event?: string;
+    slug?: string | null;
+    summary?: string | null;
+    createdAt?: string | null;
+    actorKind?: string | null;
+};
+/** Same resolution as the credential/session stores: OXYGEN_CONFIG_DIR wins. */
+export declare function resolveDefaultConfigDir(env?: NodeJS.ProcessEnv): string;
+export declare function resolveMirrorDir(input: {
+    configDir: string;
+    apiHost: string;
+    orgId: string;
+}): string;
+export declare function mirrorSidecarDir(dir: string): string;
+export declare function mirrorManifestPath(dir: string): string;
+export declare function mirrorLockPath(dir: string): string;
+export declare function mirrorConflictsDir(dir: string): string;
+export declare function pageFilePath(dir: string, slug: string): string;
+/** Cheap "does a mirror exist here" check for post-write staleness hooks. */
+export declare function mirrorExists(dir: string): boolean;
+export declare function assertSafeMirrorSlug(slug: string): void;
+export declare function emptyMirrorState(input: {
+    apiHost: string;
+    orgId: string;
+}): MirrorState;
+/** Null on a missing or corrupt manifest — the next sync re-clones from scratch. */
+export declare function readMirrorState(dir: string): MirrorState | null;
+export declare function writeMirrorState(dir: string, state: MirrorState): void;
+/** Clear last_sync_at so the next `knowledge sync --if-stale` runs for real. */
+export declare function markMirrorStale(dir: string): void;
+export declare function findMirrorSlugByPageId(state: MirrorState, pageId: string): string | null;
+export declare function writePageFile(dir: string, slug: string, bytes: string): void;
+export declare function deletePageFile(dir: string, slug: string): void;
+/** sha256 hex of the local page file bytes, or null when the file is missing. */
+export declare function localPageSha256(dir: string, slug: string): string | null;
+/** A missing file is never dirty; anything whose bytes differ from expectedSha256 is. */
+export declare function isFileDirty(dir: string, slug: string, expectedSha256: string): boolean;
+/**
+ * Move the CURRENT local page file into .oxygen/conflicts/<slug>-<timestamp>.md
+ * so a locally edited copy survives the incoming server write. Returns the
+ * conflict path, or null when there was no local file to preserve.
+ */
+export declare function quarantineDirtyFile(dir: string, slug: string): string | null;
+export declare function listConflictFiles(dir: string): string[];
+export declare function clearConflictFiles(dir: string): number;
+/**
+ * Take the mirror's sync lock (a pid file created with O_EXCL). Returns false
+ * while another sync holds a fresh lock; a lock older than MIRROR_LOCK_STALE_MS
+ * (a crashed sync) is broken and re-taken.
+ */
+export declare function acquireMirrorLock(dir: string, options?: {
+    staleMs?: number;
+}): boolean;
+export declare function releaseMirrorLock(dir: string): void;
+export declare function writeGeneratedIndexFile(dir: string, index: MirrorIndexSnapshot): void;
+export declare function writeGeneratedLogFile(dir: string, entries: MirrorLogEntry[]): void;
+/** Delete the whole mirror (pages, generated files, sidecar). Safe on a missing dir. */
+export declare function purgeMirror(dir: string): void;
+/**
+ * Reset the mirror for `sync --full` WITHOUT destroying evidence of local edits: every
+ * manifest page whose local bytes drifted from its recorded sha is quarantined into
+ * `.oxygen/conflicts/` first, and the conflicts dir survives the reset. A plain purge
+ * (logout / access revoked / `knowledge purge`) deliberately preserves nothing — this
+ * variant exists only so `--full` keeps the never-silently-clobber promise.
+ */
+export declare function resetMirrorForFullResync(dir: string): {
+    quarantined: number;
+};

package/dist/knowledge-mirror.js

@@ -0,0 +1,375 @@
+// Local knowledge-wiki mirror directory management for `oxygen knowledge sync` —
+// pure filesystem state, no network. The mirror stores SERVER-rendered markdown
+// bytes verbatim: the server renders + hashes every page (content_sha256) and the
+// client never re-renders, so renderer drift can't mass-quarantine mirrors (see
+// packages/shared/src/knowledge-markdown.ts). Layout:
+//
+//   <configDir>/knowledge/<api-host>/<org-id>/
+//     <slug>.md            synced wiki pages (server bytes, 0600)
+//     index.md, log.md     generated summaries (marker header, always overwritten)
+//     .oxygen/             sidecar: manifest.json, lock, conflicts/<slug>-<ts>.md
+//
+// Locally edited page files are never silently clobbered: the sync loop moves
+// dirty bytes into .oxygen/conflicts/ before rewriting. The generated index.md
+// and log.md are the one exception — their marker header says so.
+import { createHash } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { OxygenError } from "@oxygen/shared";
+const MIRROR_SIDECAR_DIRNAME = ".oxygen";
+const MIRROR_MANIFEST_FILENAME = "manifest.json";
+const MIRROR_LOCK_FILENAME = "lock";
+const MIRROR_CONFLICTS_DIRNAME = "conflicts";
+const MIRROR_SLUG_MAX_LENGTH = 200;
+export const MIRROR_LOCK_STALE_MS = 10 * 60 * 1000;
+// Server page slugs are lowercase alphanumerics/dashes; anything else (path
+// separators, dots, uppercase) is rejected before it can touch the filesystem.
+export const MIRROR_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+export const GENERATED_MIRROR_FILE_HEADER = "<!-- generated by oxygen knowledge sync — local edits are overwritten -->";
+// ── Paths ───────────────────────────────────────────────────────────────────────
+/** Same resolution as the credential/session stores: OXYGEN_CONFIG_DIR wins. */
+export function resolveDefaultConfigDir(env = process.env) {
+    return env.OXYGEN_CONFIG_DIR?.trim()
+        || (process.platform === "win32"
+            ? join(env.APPDATA || join(homedir(), "AppData", "Roaming"), "oxygen")
+            : join(homedir(), ".config", "oxygen"));
+}
+export function resolveMirrorDir(input) {
+    return join(input.configDir, "knowledge", safePathSegment(input.apiHost, "API host"), safePathSegment(input.orgId, "organization id"));
+}
+export function mirrorSidecarDir(dir) {
+    return join(dir, MIRROR_SIDECAR_DIRNAME);
+}
+export function mirrorManifestPath(dir) {
+    return join(mirrorSidecarDir(dir), MIRROR_MANIFEST_FILENAME);
+}
+export function mirrorLockPath(dir) {
+    return join(mirrorSidecarDir(dir), MIRROR_LOCK_FILENAME);
+}
+export function mirrorConflictsDir(dir) {
+    return join(mirrorSidecarDir(dir), MIRROR_CONFLICTS_DIRNAME);
+}
+export function pageFilePath(dir, slug) {
+    assertSafeMirrorSlug(slug);
+    return join(dir, `${slug}.md`);
+}
+/** Cheap "does a mirror exist here" check for post-write staleness hooks. */
+export function mirrorExists(dir) {
+    return existsSync(mirrorManifestPath(dir));
+}
+function safePathSegment(value, label) {
+    const cleaned = value.trim().toLowerCase().replace(/[^a-z0-9._-]/g, "_");
+    if (!cleaned || /^\.+$/.test(cleaned)) {
+        throw new OxygenError("invalid_mirror_path", `Cannot derive a mirror directory from this ${label}.`, {
+            details: { value },
+            exitCode: 1,
+        });
+    }
+    return cleaned;
+}
+export function assertSafeMirrorSlug(slug) {
+    if (slug.length > MIRROR_SLUG_MAX_LENGTH || !MIRROR_SLUG_PATTERN.test(slug)) {
+        throw new OxygenError("invalid_slug", "Mirror page slugs must be lowercase alphanumerics and dashes.", {
+            details: { slug },
+            exitCode: 1,
+        });
+    }
+}
+// Every destructive/recursive operation double-checks it is pointed at a
+// <configDir>/knowledge/<host>/<org> directory so a mis-resolved path can never
+// delete outside the mirror namespace.
+function assertMirrorShapedDir(dir) {
+    if (!basename(dir) || basename(dirname(dirname(dir))) !== "knowledge") {
+        throw new OxygenError("invalid_mirror_path", "Refusing to operate outside a knowledge mirror directory.", {
+            details: { dir },
+            exitCode: 1,
+        });
+    }
+}
+function ensureMirrorScaffold(dir) {
+    assertMirrorShapedDir(dir);
+    const conflictsDir = mirrorConflictsDir(dir);
+    mkdirSync(conflictsDir, { recursive: true, mode: 0o700 });
+    // Recursive mkdir applies the mode to created leaves only on some platforms —
+    // pin every mirror-owned level (knowledge root down) to 0700 explicitly.
+    for (const level of [dirname(dirname(dir)), dirname(dir), dir, mirrorSidecarDir(dir), conflictsDir]) {
+        chmodSync(level, 0o700);
+    }
+}
+// Same tmp+rename pattern as the credential store: a crash mid-write can never
+// leave a torn page or manifest behind.
+function writeFileAtomic(path, contents) {
+    const tempPath = `${path}.${process.pid}.tmp`;
+    writeFileSync(tempPath, contents, { mode: 0o600 });
+    chmodSync(tempPath, 0o600);
+    renameSync(tempPath, path);
+    chmodSync(path, 0o600);
+}
+// ── Manifest state ──────────────────────────────────────────────────────────────
+export function emptyMirrorState(input) {
+    return {
+        api_host: input.apiHost,
+        org_id: input.orgId,
+        cursor: null,
+        last_sync_at: null,
+        pages: {},
+    };
+}
+// Parse the manifest's `pages` map, dropping any entry whose slug or record shape
+// is invalid so a partially corrupt manifest degrades to fewer pages, not null.
+function parseMirrorPages(rawPages) {
+    const pages = {};
+    for (const [slug, value] of Object.entries(rawPages)) {
+        if (slug.length > MIRROR_SLUG_MAX_LENGTH || !MIRROR_SLUG_PATTERN.test(slug))
+            continue;
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            continue;
+        const page = value;
+        if (typeof page.id !== "string" || typeof page.content_sha256 !== "string")
+            continue;
+        pages[slug] = {
+            id: page.id,
+            revision: typeof page.revision === "number" && Number.isFinite(page.revision) ? page.revision : 0,
+            content_sha256: page.content_sha256,
+        };
+    }
+    return pages;
+}
+/** Null on a missing or corrupt manifest — the next sync re-clones from scratch. */
+export function readMirrorState(dir) {
+    const path = mirrorManifestPath(dir);
+    if (!existsSync(path))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    const record = parsed;
+    const rawPages = record.pages;
+    if (typeof record.api_host !== "string" || typeof record.org_id !== "string")
+        return null;
+    if (!rawPages || typeof rawPages !== "object" || Array.isArray(rawPages))
+        return null;
+    const pages = parseMirrorPages(rawPages);
+    return {
+        api_host: record.api_host,
+        org_id: record.org_id,
+        cursor: typeof record.cursor === "string" && record.cursor ? record.cursor : null,
+        last_sync_at: typeof record.last_sync_at === "string" && record.last_sync_at ? record.last_sync_at : null,
+        pages,
+    };
+}
+export function writeMirrorState(dir, state) {
+    ensureMirrorScaffold(dir);
+    writeFileAtomic(mirrorManifestPath(dir), `${JSON.stringify(state, null, 2)}\n`);
+}
+/** Clear last_sync_at so the next `knowledge sync --if-stale` runs for real. */
+export function markMirrorStale(dir) {
+    const state = readMirrorState(dir);
+    if (!state || state.last_sync_at === null)
+        return;
+    writeMirrorState(dir, { ...state, last_sync_at: null });
+}
+export function findMirrorSlugByPageId(state, pageId) {
+    for (const [slug, record] of Object.entries(state.pages)) {
+        if (record.id === pageId)
+            return slug;
+    }
+    return null;
+}
+// ── Page files ──────────────────────────────────────────────────────────────────
+export function writePageFile(dir, slug, bytes) {
+    const path = pageFilePath(dir, slug);
+    ensureMirrorScaffold(dir);
+    writeFileAtomic(path, bytes);
+}
+export function deletePageFile(dir, slug) {
+    rmSync(pageFilePath(dir, slug), { force: true });
+}
+/** sha256 hex of the local page file bytes, or null when the file is missing. */
+export function localPageSha256(dir, slug) {
+    const path = pageFilePath(dir, slug);
+    if (!existsSync(path))
+        return null;
+    return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+/** A missing file is never dirty; anything whose bytes differ from expectedSha256 is. */
+export function isFileDirty(dir, slug, expectedSha256) {
+    const localSha = localPageSha256(dir, slug);
+    return localSha !== null && localSha !== expectedSha256;
+}
+/**
+ * Move the CURRENT local page file into .oxygen/conflicts/<slug>-<timestamp>.md
+ * so a locally edited copy survives the incoming server write. Returns the
+ * conflict path, or null when there was no local file to preserve.
+ */
+export function quarantineDirtyFile(dir, slug) {
+    const source = pageFilePath(dir, slug);
+    if (!existsSync(source))
+        return null;
+    ensureMirrorScaffold(dir);
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    let destination = join(mirrorConflictsDir(dir), `${slug}-${stamp}.md`);
+    for (let suffix = 2; existsSync(destination); suffix += 1) {
+        destination = join(mirrorConflictsDir(dir), `${slug}-${stamp}-${suffix}.md`);
+    }
+    renameSync(source, destination);
+    chmodSync(destination, 0o600);
+    return destination;
+}
+export function listConflictFiles(dir) {
+    const conflictsDir = mirrorConflictsDir(dir);
+    if (!existsSync(conflictsDir))
+        return [];
+    return readdirSync(conflictsDir)
+        .filter((name) => name.endsWith(".md"))
+        .sort((a, b) => a.localeCompare(b));
+}
+export function clearConflictFiles(dir) {
+    const names = listConflictFiles(dir);
+    for (const name of names) {
+        rmSync(join(mirrorConflictsDir(dir), name), { force: true });
+    }
+    return names.length;
+}
+// ── Locking ─────────────────────────────────────────────────────────────────────
+/**
+ * Take the mirror's sync lock (a pid file created with O_EXCL). Returns false
+ * while another sync holds a fresh lock; a lock older than MIRROR_LOCK_STALE_MS
+ * (a crashed sync) is broken and re-taken.
+ */
+export function acquireMirrorLock(dir, options = {}) {
+    ensureMirrorScaffold(dir);
+    const lockPath = mirrorLockPath(dir);
+    const payload = `${JSON.stringify({ pid: process.pid, acquired_at: new Date().toISOString() })}\n`;
+    const staleMs = options.staleMs ?? MIRROR_LOCK_STALE_MS;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            writeFileSync(lockPath, payload, { mode: 0o600, flag: "wx" });
+            return true;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            let heldSinceMs;
+            try {
+                heldSinceMs = statSync(lockPath).mtimeMs;
+            }
+            catch {
+                continue; // the holder released between write and stat — retry the acquire
+            }
+            if (Date.now() - heldSinceMs < staleMs)
+                return false;
+            rmSync(lockPath, { force: true }); // stale holder — break the lock and retry
+        }
+    }
+    return false;
+}
+export function releaseMirrorLock(dir) {
+    rmSync(mirrorLockPath(dir), { force: true });
+}
+// ── Generated files (index.md / log.md) ─────────────────────────────────────────
+// Always overwritten, never quarantined: they summarize server projections and the
+// marker header warns that local edits are lost on the next sync.
+export function writeGeneratedIndexFile(dir, index) {
+    const pages = index.pages.filter((page) => MIRROR_SLUG_PATTERN.test(page.slug));
+    const total = index.counts?.total ?? pages.length;
+    const lines = [
+        GENERATED_MIRROR_FILE_HEADER,
+        "",
+        "# Knowledge wiki index",
+        "",
+        `${total} page${total === 1 ? "" : "s"}. Regenerated by every \`oxygen knowledge sync\`.`,
+        "",
+    ];
+    for (const page of pages) {
+        const meta = [
+            page.type ? oneLine(page.type) : null,
+            page.revision !== undefined ? `rev ${page.revision}` : null,
+            page.canonical ? "canonical" : null,
+        ].filter(Boolean).join(", ");
+        const title = oneLine(page.title ?? "") || page.slug;
+        const summary = page.oneLiner ? ` — ${oneLine(page.oneLiner)}` : "";
+        lines.push(`- [${page.slug}](./${page.slug}.md) — ${title}${meta ? ` (${meta})` : ""}${summary}`);
+    }
+    writeGeneratedFile(dir, "index.md", lines);
+}
+export function writeGeneratedLogFile(dir, entries) {
+    const lines = [
+        GENERATED_MIRROR_FILE_HEADER,
+        "",
+        "# Knowledge log",
+        "",
+        `${entries.length} most recent entr${entries.length === 1 ? "y" : "ies"}, newest first. Regenerated by every \`oxygen knowledge sync\`.`,
+        "",
+    ];
+    for (const entry of entries) {
+        const parts = [
+            entry.createdAt ? oneLine(entry.createdAt) : null,
+            entry.event ? oneLine(entry.event) : null,
+            entry.slug ? `[[${oneLine(entry.slug)}]]` : null,
+            entry.summary ? oneLine(entry.summary) : null,
+        ].filter(Boolean);
+        lines.push(`- ${parts.join(" — ")}${entry.seq ? ` (seq ${oneLine(entry.seq)})` : ""}`);
+    }
+    writeGeneratedFile(dir, "log.md", lines);
+}
+function writeGeneratedFile(dir, name, lines) {
+    ensureMirrorScaffold(dir);
+    writeFileAtomic(join(dir, name), `${lines.join("\n")}\n`);
+}
+function oneLine(value) {
+    return value.replace(/\s+/g, " ").trim();
+}
+// ── Purge ───────────────────────────────────────────────────────────────────────
+/** Delete the whole mirror (pages, generated files, sidecar). Safe on a missing dir. */
+export function purgeMirror(dir) {
+    assertMirrorShapedDir(dir);
+    rmSync(dir, { recursive: true, force: true });
+}
+/**
+ * Reset the mirror for `sync --full` WITHOUT destroying evidence of local edits: every
+ * manifest page whose local bytes drifted from its recorded sha is quarantined into
+ * `.oxygen/conflicts/` first, and the conflicts dir survives the reset. A plain purge
+ * (logout / access revoked / `knowledge purge`) deliberately preserves nothing — this
+ * variant exists only so `--full` keeps the never-silently-clobber promise.
+ */
+export function resetMirrorForFullResync(dir) {
+    assertMirrorShapedDir(dir);
+    let quarantined = 0;
+    const state = readMirrorState(dir);
+    for (const [slug, entry] of Object.entries(state?.pages ?? {})) {
+        if (!entry?.content_sha256)
+            continue;
+        if (!isFileDirty(dir, slug, entry.content_sha256))
+            continue;
+        if (quarantineDirtyFile(dir, slug))
+            quarantined += 1;
+    }
+    let entries = [];
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return { quarantined }; // mirror never existed — nothing to reset
+    }
+    for (const entry of entries) {
+        const path = join(dir, entry);
+        if (entry === MIRROR_SIDECAR_DIRNAME) {
+            for (const side of readdirSync(path)) {
+                if (side === MIRROR_CONFLICTS_DIRNAME)
+                    continue;
+                rmSync(join(path, side), { recursive: true, force: true });
+            }
+            continue;
+        }
+        rmSync(path, { recursive: true, force: true });
+    }
+    return { quarantined };
+}

package/dist/skills.d.ts

@@ -1,4 +1,5 @@
 import { execFileSync, spawnSync } from "node:child_process";
+import { type StoredCredentials } from "./credentials.js";
 export type ExecFileSyncLike = typeof execFileSync;
 export type SpawnSyncLike = typeof spawnSync;
 export type SkillsInstallOptions = {
@@ -28,20 +29,48 @@ export type AutomaticSkillsInstallResult = {
         details?: unknown;
     };
 };
-export declare function listAgentSkills(options: SkillsListOptions): Promise<Record<string, unknown>>;
-export declare function doctorAgentSkills(options: SkillsDoctorOptions): Promise<Record<string, unknown>>;
+export type SkillsAccessResponse = {
+    base_url: string;
+    index_url: string;
+    expires_at: string;
+    skills_version?: string;
+};
+export type SkillsInstallSource = {
+    authenticated: boolean;
+    /** Base URL handed to `npx skills add` (tokenized when authenticated). */
+    install_url: string;
+    /** Concrete index.json URL, fetched by list/doctor. */
+    index_url: string;
+    expires_at?: string;
+    fallback_reason?: string;
+};
+export type SkillsSourceRuntime = {
+    credentials?: StoredCredentials | null;
+    fetch?: typeof fetch;
+};
+/**
+ * Resolves where to install skills from. Logged-in CLIs mint a short-lived
+ * org-bound access URL (the skills surface is gated; anonymous serving is
+ * being retired). Any failure falls back to the plain well-known URL so
+ * installs never regress while older deployments are still in circulation.
+ */
+export declare function resolveSkillsInstallSource(options: {
+    apiUrl: string;
+} & SkillsSourceRuntime): Promise<SkillsInstallSource>;
+export declare function listAgentSkills(options: SkillsListOptions, runtime?: SkillsSourceRuntime): Promise<Record<string, unknown>>;
+export declare function doctorAgentSkills(options: SkillsDoctorOptions, runtime?: SkillsSourceRuntime): Promise<Record<string, unknown>>;
 export declare function installAgentSkills(// skipcq: JS-R1005
 options: SkillsInstallOptions, runtime?: {
     env?: NodeJS.ProcessEnv;
     platform?: NodeJS.Platform;
     execFileSync?: ExecFileSyncLike;
     spawnSync?: SpawnSyncLike;
-}): Record<string, unknown>;
+} & SkillsSourceRuntime): Promise<Record<string, unknown>>;
 export declare function runAutomaticSkillsInstall(options?: {
     apiUrl?: string;
     env?: NodeJS.ProcessEnv;
     platform?: NodeJS.Platform;
     execFileSync?: ExecFileSyncLike;
     spawnSync?: SpawnSyncLike;
-}): AutomaticSkillsInstallResult;
+} & SkillsSourceRuntime): Promise<AutomaticSkillsInstallResult>;
 export declare function skippedAutomaticSkillsInstall(reason: string, apiUrl?: string): AutomaticSkillsInstallResult;