@oxygen-agent/cli 1.936.1 → 1.982.3

package/dist/knowledge-repository-commands.d.ts

@@ -0,0 +1,6 @@
+import { Command } from "commander";
+type Handle = (command: string, options: {
+    json?: boolean;
+}, action: () => Promise<unknown>) => Promise<void>;
+export declare function registerKnowledgeRepositoryCommands(program: Command, handle: Handle): void;
+export {};

package/dist/knowledge-repository-commands.js

@@ -0,0 +1,198 @@
+import { readFile, writeFile, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import { requestOxygen } from "./http-client.js";
+const post = (path, body) => {
+    if (Buffer.byteLength(JSON.stringify(body)) > 2_000_000)
+        throw new Error("This inline request exceeds 2 MB. Add larger attachments through the connected GitHub repository.");
+    return requestOxygen(`/api/cli/knowledge/${path}`, { method: "POST", body });
+};
+export function registerKnowledgeRepositoryCommands(program, handle) {
+    const knowledge = program.commands.find((c) => c.name() === "knowledge");
+    if (!knowledge)
+        throw new Error("Knowledge commands must be registered first.");
+    const repos = knowledge
+        .command("repositories")
+        .description("Import an existing GitHub or Obsidian repository into Knowledge, or keep it automatically in sync. Start with integrations connect github; web setup: /knowledge/repositories; docs: /docs/knowledge/knowledge-graph.");
+    repos
+        .command("list")
+        .description("Read connected repositories, import progress, sync freshness, pending changes, and errors. 0 credits.")
+        .option("--json", "Print a JSON envelope.")
+        .action((o) => handle("knowledge repositories list", o, () => post("repositories/list", {})));
+    for (const operation of ["preview", "connect"]) {
+        const cmd = repos
+            .command(operation)
+            .description(operation === "preview"
+            ? "Preview branch/folder contents, exclusions and the future sync policy. Does not activate sync. 0 credits."
+            : "Approve the exact preview and start importing. two_way authorizes future automatic GitHub writes to the selected branch. 0 Oxygen credits.")
+            .requiredOption("--connection-id <id>", "GitHub connection ID from integrations list.")
+            .requiredOption("--repository-id <id>", "Repository ID from integrations github repositories.")
+            .requiredOption("--branch <name>", "Connected branch; unmerged feature branches are separate.")
+            .option("--root-path <path>", "Repository subfolder; omit for the entire repository.", "")
+            .option("--mode <mode>", "two_way or import (one-time copy).", "two_way")
+            .option("--json", "Print a JSON envelope.");
+        if (operation === "connect")
+            cmd
+                .requiredOption("--preview-token <token>", "Exact token returned by repositories preview.")
+                .option("--approved", "Approve the displayed import and future sync policy.");
+        cmd.action((o) => handle(`knowledge repositories ${operation}`, o, () => post(`repositories/${operation}`, {
+            connectionId: o.connectionId,
+            repositoryId: Number(o.repositoryId),
+            branch: o.branch,
+            rootPath: o.rootPath,
+            mode: o.mode,
+            ...(operation === "connect"
+                ? { previewToken: o.previewToken, approved: o.approved === true }
+                : {}),
+        })));
+    }
+    for (const action of ["sync", "pause", "resume", "disconnect"]) {
+        const description = {
+            sync: "Request an immediate sync attempt. Saved changes remain safe if GitHub is unavailable.",
+            pause: "Pause automatic sync; keep all imported files and history.",
+            resume: "Resume the previously approved sync policy.",
+            disconnect: "Disconnect this repository; keep its files and history in Knowledge.",
+        }[action];
+        repos
+            .command(action)
+            .description(description)
+            .requiredOption("--id <id>", "Connected repository mount ID.")
+            .option("--json", "Print a JSON envelope.")
+            .action((o) => handle(`knowledge repositories ${action}`, o, () => post("repositories/action", { id: o.id, action })));
+    }
+    repos
+        .command("conflicts")
+        .description("Read conflicts; add --path to inspect preserved base, Oxygen, and GitHub versions.")
+        .requiredOption("--mount-id <id>", "Connected repository mount ID.")
+        .option("--path <path>", "Exact file path.")
+        .option("--json", "Print a JSON envelope.")
+        .action((o) => handle("knowledge repositories conflicts", o, () => post("repositories/conflicts", {
+        mountId: o.mountId,
+        ...(o.path ? { path: o.path } : {}),
+    })));
+    repos
+        .command("resolve")
+        .description("Apply a reviewed conflict decision. Canonical copy remains proposal-gated; GitHub publishes under the saved sync policy.")
+        .requiredOption("--mount-id <id>", "Connected repository mount ID.")
+        .requiredOption("--path <path>", "Exact file path.")
+        .requiredOption("--local-revision <revision|null>", "Reviewed Oxygen revision or null.")
+        .requiredOption("--remote-sha <sha|null>", "Reviewed GitHub blob SHA or null.")
+        .requiredOption("--decision <choice>", "oxygen, github, or merged.")
+        .option("--file <path>", "Complete edited UTF-8 file for merged.")
+        .option("--approved", "Approve this exact decision.")
+        .option("--json", "Print a JSON envelope.")
+        .action((o) => handle("knowledge repositories resolve", o, async () => post("repositories/resolve", {
+        mountId: o.mountId,
+        path: o.path,
+        expectedLocalRevision: o.localRevision === "null" ? null : Number(o.localRevision),
+        expectedRemoteSha: o.remoteSha === "null" ? null : o.remoteSha,
+        decision: o.decision,
+        ...(o.file ? { text: await readFile(String(o.file), "utf8") } : {}),
+        approved: o.approved === true,
+    })));
+    const files = knowledge
+        .command("files")
+        .description("Original repository paths and immutable file revisions, including attachments.");
+    files
+        .command("list")
+        .requiredOption("--mount-id <id>", "Connected repository ID.")
+        .option("--cursor <cursor>", "Continue the previous page.")
+        .option("--limit <number>", "Maximum files, up to 500.", "100")
+        .option("--json", "Print a JSON envelope.")
+        .action((o) => handle("knowledge files list", o, () => post("files/list", {
+        mountId: o.mountId,
+        limit: Number(o.limit),
+        ...(o.cursor ? { cursor: o.cursor } : {}),
+    })));
+    files
+        .command("get")
+        .description("Read original file content, properties and download link at an optional immutable revision.")
+        .requiredOption("--id <id>", "File ID from files list.")
+        .option("--revision <number>", "Specific saved file revision.")
+        .option("--json", "Print a JSON envelope.")
+        .action((o) => handle("knowledge files get", o, () => post("files/get", {
+        id: o.id,
+        ...(o.revision ? { revision: Number(o.revision) } : {}),
+    })));
+    files
+        .command("upsert")
+        .description("Create or replace an original file, or update frontmatter properties. Canonical copy still requires a proposal.")
+        .requiredOption("--mount-id <id>", "Connected repository ID.")
+        .option("--id <id>", "Existing file ID.")
+        .option("--path <path>", "Exact repository-relative path; required for new files.")
+        .requiredOption("--expected-revision <number>", "Reviewed file revision; 0 creates a new file.")
+        .option("--file <path>", "Complete local file, including any frontmatter or binary bytes.")
+        .option("--properties-json <json>", "Frontmatter properties to change; mutually exclusive with --file.")
+        .option("--json", "Print a JSON envelope.")
+        .action((o) => handle("knowledge files upsert", o, async () => {
+        if (Boolean(o.file) === Boolean(o.propertiesJson))
+            throw new Error("Provide exactly one of --file or --properties-json.");
+        if (o.file && (await stat(String(o.file))).size > 1_500_000)
+            throw new Error("Inline file uploads must fit a 2 MB JSON request (including base64). Add larger attachments through the connected GitHub repository.");
+        const patch = o.propertiesJson
+            ? JSON.parse(String(o.propertiesJson))
+            : undefined;
+        if (patch !== undefined &&
+            (!patch || typeof patch !== "object" || Array.isArray(patch)))
+            throw new Error("--properties-json must contain an object.");
+        return post("files/upsert", {
+            mountId: o.mountId,
+            ...(o.id ? { id: o.id } : {}),
+            ...(o.path ? { path: o.path } : {}),
+            expectedFileRevision: Number(o.expectedRevision),
+            ...(o.file
+                ? {
+                    bytesBase64: (await readFile(String(o.file))).toString("base64"),
+                }
+                : { propertyPatch: patch }),
+        });
+    }));
+    files
+        .command("archive")
+        .description("Archive a file with revision checking. A connected two-way repository publishes the deletion; history remains.")
+        .requiredOption("--id <id>", "File ID.")
+        .requiredOption("--expected-revision <number>", "Reviewed file revision.")
+        .option("--json", "Print a JSON envelope.")
+        .action((o) => handle("knowledge files archive", o, () => post("files/archive", {
+        id: o.id,
+        expectedFileRevision: Number(o.expectedRevision),
+    })));
+    files
+        .command("download")
+        .description("Download exact original bytes with digest verification; refuses to overwrite an existing local file.")
+        .requiredOption("--id <id>", "File ID.")
+        .requiredOption("--out <path>", "New local destination filename.")
+        .option("--revision <number>", "Specific immutable revision.")
+        .option("--json", "Print a JSON envelope.")
+        .action((o) => handle("knowledge files download", o, async () => {
+        const query = new URLSearchParams({
+            id: String(o.id),
+            ...(o.revision ? { revision: String(o.revision) } : {}),
+        });
+        const data = await requestOxygen(`/api/cli/knowledge/files/get?${query}`);
+        const bytes = await requestOxygen(`/api/cli/knowledge/files/download?${query}`, { binaryMaxBytes: Math.max(1, data.file.sizeBytes) });
+        if (bytes.length !== data.file.sizeBytes ||
+            createHash("sha256").update(bytes).digest("hex") !== data.file.sha256)
+            throw new Error("Downloaded bytes do not match the saved file revision.");
+        await writeFile(String(o.out), bytes, { flag: "wx", mode: 0o600 });
+        return { path: resolve(String(o.out)), ...data.file };
+    }));
+    const integrations = program.commands.find((c) => c.name() === "integrations");
+    if (integrations) {
+        const github = integrations
+            .command("github")
+            .description("Choose repositories authorized through the GitHub App. Connect first with integrations connect github. The Oxygen GitHub App requests Contents read and write plus Metadata read on the repositories you select, and push events; it requests no account or organization permissions. integrations list reports GitHub availability for this deployment.");
+        github
+            .command("repositories")
+            .requiredOption("--connection-id <id>", "GitHub connection ID.")
+            .option("--json", "Print a JSON envelope.")
+            .action((o) => handle("integrations github repositories", o, () => requestOxygen(`/api/cli/integrations/github/repositories?connection_id=${encodeURIComponent(String(o.connectionId))}`)));
+        github
+            .command("branches")
+            .requiredOption("--connection-id <id>", "GitHub connection ID.")
+            .requiredOption("--repository-id <id>", "Immutable GitHub repository ID.")
+            .option("--page <number>", "Page to read.", "1")
+            .option("--json", "Print a JSON envelope.")
+            .action((o) => handle("integrations github branches", o, () => requestOxygen(`/api/cli/integrations/github/branches?${new URLSearchParams({ connection_id: String(o.connectionId), repository_id: String(o.repositoryId), page: String(o.page) })}`)));
+    }
+}

package/dist/skills.js

@@ -66,6 +66,17 @@ export async function resolveSkillsInstallSource(options) {
         return publicSource(`access_unavailable:${code}`);
     }
 }
+function requireSkillContentAccess(index, source) {
+    if (!index.authentication_required)
+        return;
+    throw new OxygenError("skills_authentication_required", "Sign in to download Oxygen agent instructions.", {
+        details: {
+            next_step: "Run `oxygen login`, then retry `oxygen skills install` or `oxygen skills get`.",
+            ...(source.fallback_reason ? { access_fallback: source.fallback_reason } : {}),
+        },
+        exitCode: 1,
+    });
+}
 export async function listAgentSkills(options, runtime = {}) {
     const apiUrl = normalizeApiUrl(readOption(options.apiUrl) ?? defaultApiUrl());
     const source = await resolveSkillsInstallSource({ apiUrl, ...runtime });
@@ -137,6 +148,7 @@ export async function getAgentSkill(skillName, options, runtime = {}) {
             exitCode: 1,
         });
     }
+    requireSkillContentAccess(index, source);
     const normalized = skillName.trim();
     const skill = index.skills.find((entry) => entry.name === normalized);
     if (!skill) {
@@ -203,6 +215,12 @@ options, runtime = {}) {
         ...(runtime.credentials !== undefined ? { credentials: runtime.credentials } : {}),
         ...(runtime.fetch ? { fetch: runtime.fetch } : {}),
     });
+    if (!source.authenticated) {
+        // Public discovery remains usable. New servers explicitly mark that their
+        // instruction bodies require a signed workspace link; never invoke the
+        // installer against that discovery-only catalog.
+        requireSkillContentAccess(await inspectSkillIndex(source.index_url, runtime.fetch), source);
+    }
     const agents = readWords(options.agents ?? DEFAULT_SKILL_AGENTS);
     const skill = readOption(options.skill) ?? "*";
     const env = runtime.env ?? process.env;
@@ -599,6 +617,7 @@ async function inspectSkillIndex(indexUrl, fetchImpl = fetch) {
         }
         return {
             reachable: true,
+            authentication_required: index.authentication_required === true,
             status: response.status,
             version: index.version,
             base_url: index.base_url,
@@ -667,6 +686,7 @@ function parseSkillIndex(value) {
     })
         .filter((entry) => entry !== null);
     return {
+        authentication_required: value.authentication_required === true,
         version: typeof value.version === "string" ? value.version : null,
         base_url: typeof value.base_url === "string" ? value.base_url : null,
         skills,