@amoree-code/ocean 0.0.0-stage → 1.2.0

package/dist/application/layout/workspace-template.js

@@ -0,0 +1,34 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { oceanRoot } from "@ocean/core/shared/paths.js";
+// The workspace template shipped in the package (T-296 §3.9): generic charter, policies,
+// templates and indexes, empty private files, and the required empty directories. Its classes
+// live in MANIFEST.json and are checked by scripts/check-template-purity.mjs.
+export const WORKSPACE_TEMPLATE = fileURLToPath(new URL("../../../templates/workspace/", import.meta.url));
+// Copies every template file the workspace does not have yet and creates the required
+// directories. A file that already exists is never replaced, so a rerun on a populated
+// workspace changes nothing. `.gitkeep` files are not copied: they only keep the template's
+// empty directories in git.
+export async function seedWorkspaceTemplate(root = oceanRoot(), template = WORKSPACE_TEMPLATE) {
+    const manifest = JSON.parse(await readFile(path.join(template, "MANIFEST.json"), "utf8"));
+    const created = [];
+    const kept = [];
+    for (const [file, kind] of Object.entries(manifest.files)) {
+        const target = path.join(root, ...file.split("/"));
+        await mkdir(path.dirname(target), { recursive: true });
+        if (kind === "keep")
+            continue;
+        try {
+            await writeFile(target, await readFile(path.join(template, ...file.split("/"))), { flag: "wx" });
+            created.push(file);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            kept.push(file);
+        }
+    }
+    return { created, kept };
+}
+//# sourceMappingURL=workspace-template.js.map

package/dist/application/onboarding/state.js

@@ -0,0 +1,23 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { oceanPath, SYSTEM_DIR } from "@ocean/core/shared/paths.js";
+export function onboardingStatePath() {
+    return oceanPath(SYSTEM_DIR, "state", "onboarding.json");
+}
+export async function loadOnboardingState() {
+    try {
+        const parsed = JSON.parse(await readFile(onboardingStatePath(), "utf8"));
+        return { version: parsed.version ?? 0, steps: parsed.steps ?? {} };
+    }
+    catch {
+        return { version: 0, steps: {} };
+    }
+}
+export async function saveOnboardingState(state) {
+    const file = onboardingStatePath();
+    await mkdir(path.dirname(file), { recursive: true });
+    const temporary = `${file}.${process.pid}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(state, null, 2)}\n`);
+    await rename(temporary, file);
+}
+//# sourceMappingURL=state.js.map

package/dist/application/onboarding/steps.js

@@ -0,0 +1,249 @@
+import { writeFile } from "node:fs/promises";
+import { oceanPath, PERSONAL_DIR } from "@ocean/core/shared/paths.js";
+import { copyClientSkills, populateSkillHub, } from "@ocean/market/skills/skill-hub.js";
+import { connectObsidianVault } from "@ocean/services/obsidian/vault-discovery.js";
+// Bump when a step is added; completed steps stay completed, only new ids run.
+export const ONBOARDING_VERSION = 3;
+async function yes(io, question) {
+    return (await io.ask(`${question} [Y/n] `, "y")).trim().toLowerCase() !== "n";
+}
+function describeClient(plan) {
+    if (plan.status === "current")
+        return "connected";
+    if (plan.status === "change")
+        return `will ${plan.ops.map((op) => `${op.kind} ${op.key}`).join(", ")} in ${plan.file}`;
+    if (plan.status === "manual")
+        return `hand edit needed (${plan.reason})`;
+    if (plan.status === "unknown")
+        return `unknown: ${plan.reason}`;
+    return `${plan.status}: ${plan.reason}; fallback: ${plan.fallback}`;
+}
+// T-296 §3.7: one consolidated review of every detected client (MCP entry and session hook), one
+// confirmation for all of them. Without a terminal nothing is written: client configs change
+// only on an explicit yes.
+function connectStep(clients) {
+    return {
+        id: "connect",
+        title: "Connect AI clients to Ocean (one review, one apply)",
+        optional: false,
+        // Drift of an approved client is repaired by `client sync`; only a new one needs a review.
+        async reopen() {
+            const approved = new Set(await clients.approved());
+            const fresh = (await clients.plan())
+                .filter((plan) => plan.installed &&
+                plan.status === "change" &&
+                !approved.has(plan.client))
+                .map((plan) => plan.client);
+            return fresh.length
+                ? `new client(s) to connect: ${fresh.join(", ")}`
+                : null;
+        },
+        async run(io) {
+            const plans = (await clients.plan()).filter((plan) => plan.installed);
+            for (const plan of plans)
+                io.say(`  ${plan.label.padEnd(34)} ${describeClient(plan)}`);
+            for (const plan of plans.filter((item) => item.status === "manual"))
+                io.say(`  Hand edit for ${plan.label} (${plan.file}): add ${plan.snippet}`);
+            const hooks = await clients.hooks();
+            for (const hook of hooks)
+                io.say(`  ${`${hook.client} ${hook.event} hook`.padEnd(34)} ${hook.status === "current"
+                    ? "present"
+                    : hook.status === "change"
+                        ? `will add a ${hook.event} hook in ${hook.file}`
+                        : `hand edit needed (${hook.reason})${hook.snippet ? `; add ${hook.snippet}` : ""}`}`);
+            const native = await clients.native();
+            for (const item of native)
+                io.say(`  ${`${item.client} native memory`.padEnd(34)} ${item.status === "current"
+                    ? "governed"
+                    : item.status === "change"
+                        ? `will set ${item.setting} in ${item.file}`
+                        : item.status === "manual"
+                            ? `hand edit: ${item.setting} in ${item.file} (${item.reason})`
+                            : item.status === "capture"
+                                ? `captured: ${item.reason}`
+                                : `you: ${item.reason}`}`);
+            const pending = plans.filter((plan) => plan.status === "change");
+            const pendingHooks = hooks.filter((hook) => hook.status === "change");
+            const pendingNative = native.filter((item) => item.status === "change");
+            if (pending.length + pendingHooks.length + pendingNative.length === 0) {
+                io.say("  Every client Ocean can wire is already connected.");
+                return "done";
+            }
+            if (!io.interactive) {
+                io.say("  Review: ocean clients plan   Apply: ocean clients apply --yes");
+                return "skipped";
+            }
+            if (!(await yes(io, `  Apply these changes (${pending.length} MCP entries, ${pendingHooks.length} session hooks, ${pendingNative.length} native-memory settings)?`)))
+                return "skipped";
+            const { batch, results } = await clients.apply(pending.map((plan) => plan.client));
+            for (const { client, event, result } of await clients.applyHooks(batch))
+                io.say(`  ${client} ${event} hook: ${result}`);
+            for (const { client, result } of await clients.applyNative(batch))
+                io.say(`  ${client} native memory: ${result}`);
+            io.say(`  Undo with: ocean clients restore --batch ${batch}`);
+            for (const { client, result } of results) {
+                if (result !== "written") {
+                    io.say(`  ${client}: ${result}`);
+                    continue;
+                }
+                const check = await clients.verify(client);
+                io.say(`  ${client}: ${check.ok ? "PROVEN" : "NOT READY"} — ${check.detail}`);
+            }
+            io.say('  In-app check (you): restart each client, then ask it to call `ocean_ping` and `brain_search` for "Ocean".');
+            return "done";
+        },
+    };
+}
+// A guided step prints the exact command instead of running it: these touch client
+// configs, credentials or the user's own settings, which Ocean must not edit unasked.
+function guided(id, title, lines, optional = true) {
+    return {
+        id,
+        title,
+        optional,
+        async run(io) {
+            lines.forEach((line) => {
+                io.say(`    ${line}`);
+            });
+            return (await yes(io, "  Done, or will do it later?"))
+                ? "done"
+                : "skipped";
+        },
+    };
+}
+export function buildSteps(deps) {
+    return [
+        {
+            id: "workspace",
+            title: "Workspace (folders, default profile, permissions)",
+            optional: false,
+            async run() {
+                await deps.setup();
+                return "done";
+            },
+        },
+        {
+            id: "identity",
+            title: "Identity (who Ocean works for)",
+            optional: true,
+            async run(io) {
+                const name = (await io.ask("  Your name: ", "")).trim();
+                const role = (await io.ask("  Your role: ", "")).trim();
+                const language = (await io.ask("  Preferred language: ", "")).trim();
+                if (!name && !role && !language)
+                    return "skipped";
+                await writeFile(oceanPath(PERSONAL_DIR, "identity.md"), `# Identity\n\n- Name: ${name}\n- Role: ${role}\n- Language: ${language}\n`, { flag: "wx" }).catch((error) => {
+                    if (error.code !== "EEXIST")
+                        throw error;
+                    io.say("  identity.md already exists; left unchanged.");
+                });
+                return "done";
+            },
+        },
+        {
+            id: "clients",
+            title: "AI clients (which CLIs Ocean observes)",
+            optional: false,
+            async run(io) {
+                for (const client of await deps.wrappers.wrapperStatus()) {
+                    const state = client.enabled ? "enabled" : "disabled";
+                    io.say(`  ${client.id.padEnd(12)} ${state}`);
+                    if (!io.interactive)
+                        continue;
+                    const enable = await yes(io, `  Observe ${client.id}?`);
+                    if (enable !== client.enabled)
+                        await deps.wrappers.setProviderEnabled(client.id, enable);
+                }
+                await deps.wrappers.syncProviderWrappers();
+                return "done";
+            },
+        },
+        {
+            id: "skills",
+            title: "Skills (one store in Ocean, clients hold copies)",
+            optional: false,
+            async run(io) {
+                const hub = await populateSkillHub();
+                io.say(`  Hub: ${hub.added.length} added, ${hub.kept.length} already there.`);
+                const plan = await copyClientSkills({});
+                const pending = plan.actions.filter((a) => a.action !== "synchronized");
+                if (pending.length === 0) {
+                    io.say("  Clients already hold a copy of every hub skill.");
+                    return "done";
+                }
+                io.say(`  ${pending.length} client skill copies are out of date (originals are backed up).`);
+                if (!io.interactive) {
+                    io.say("  Run: ocean skill copy --apply");
+                    return "skipped";
+                }
+                if (!(await yes(io, "  Apply now?")))
+                    return "skipped";
+                const applied = await copyClientSkills({ apply: true });
+                io.say(`  Copied. Backup: ${applied.backup ?? "none needed"}`);
+                return "done";
+            },
+        },
+        {
+            id: "shell",
+            title: "Shell integration",
+            optional: false,
+            async run(io) {
+                io.say(`  Shim directory on PATH via ${await deps.wrappers.installShellIntegration()}`);
+                return "done";
+            },
+        },
+        connectStep(deps.clients),
+        guided("auth", "Provider authentication", [
+            "Run: ocean auth",
+            "Credentials stay in the OS keychain or environment, never in files.",
+        ]),
+        guided("browser", "Browser capability", ["Run: ocean browser"]),
+        {
+            id: "obsidian",
+            title: "Obsidian vault",
+            optional: true,
+            async run(io) {
+                const vault = (await io.ask("  Vault path (blank to skip): ", "")).trim();
+                if (!vault)
+                    return "skipped";
+                const result = await connectObsidianVault(vault, "read-only");
+                io.say(`  Connected ${result.vaultPath} (${result.noteCount} notes)`);
+                return "done";
+            },
+        },
+        guided("hooks", "SessionStart auto-sync hook", [
+            "Add before the exec in your session-bootstrap hook:",
+            'node "$HOME/ocean/kernel/packages/harness/dist/main.js" client sync >/dev/null 2>&1 &',
+        ]),
+        guided("service", "Background service and schedules", [
+            "Run: ocean service   (and ocean schedule for recurring jobs)",
+        ]),
+        {
+            id: "verify",
+            title: "Verify",
+            optional: false,
+            async run(io) {
+                const findings = await deps.wrappers.wrapperDoctor();
+                // PATH is read from this process, which predates the profile edit made in the
+                // shell step, so that one finding only means "open a new terminal".
+                const pathNote = findings.filter((finding) => finding.includes("not on PATH"));
+                const blocking = findings.filter((finding) => !pathNote.includes(finding));
+                pathNote.forEach(() => {
+                    io.say("  Open a new terminal so the shim directory is on PATH.");
+                });
+                blocking.forEach((finding) => {
+                    io.say(`  NOT READY: ${finding}`);
+                });
+                if (findings.length === 0)
+                    io.say("  PROVEN: wrappers configured, binaries resolve outside the shim directory.");
+                if (blocking.length > 0) {
+                    io.say("  Fix the above, then run: ocean onboard --reset verify");
+                    return "skipped";
+                }
+                io.say("  Also run: ocean doctor");
+                return "done";
+            },
+        },
+    ];
+}
+//# sourceMappingURL=steps.js.map

package/dist/application/profiles/profile-distribution.js

@@ -0,0 +1,53 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { validateProfileDistribution, } from "@ocean/core/domain/profiles/profile-distribution.js";
+const forbidden = new Set([
+    ".env",
+    ".env.example",
+    "auth.json",
+    "memories",
+    "sessions",
+    "logs",
+    "workspace",
+    "home",
+    "state.db",
+    "state.db-shm",
+    "state.db-wal",
+]);
+export async function loadProfileDistribution(root) {
+    const manifest = JSON.parse(await readFile(path.join(root, "distribution.yaml"), "utf8"));
+    const distribution = validateProfileDistribution(manifest);
+    const files = distribution.files.length
+        ? distribution.files
+        : await listFiles(root);
+    for (const file of files) {
+        if (isForbidden(file))
+            throw new Error(`Profile distribution contains forbidden private state: ${file}`);
+        const resolved = path.resolve(root, file);
+        const rootPath = path.resolve(root);
+        if (resolved !== rootPath &&
+            !resolved.startsWith(`${rootPath}${path.sep}`)) {
+            throw new Error(`Profile distribution file escapes package root: ${file}`);
+        }
+        await stat(resolved);
+    }
+    return { ...distribution, files };
+}
+function isForbidden(file) {
+    return file
+        .split(/[\\/]/)
+        .some((part) => forbidden.has(part) || part.startsWith(".env"));
+}
+async function listFiles(root, relative = "") {
+    const directory = path.join(root, relative);
+    const result = [];
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+        const child = path.join(relative, entry.name);
+        if (entry.isDirectory())
+            result.push(...(await listFiles(root, child)));
+        else
+            result.push(child);
+    }
+    return result;
+}
+//# sourceMappingURL=profile-distribution.js.map

package/dist/application/profiles/profile-suggestion.js

@@ -0,0 +1,39 @@
+import { appendFile, mkdir, readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { suggestProfile, } from "@ocean/core/domain/profiles/profile-selection.js";
+import { parseFrontmatter } from "@ocean/core/shared/fs-utils.js";
+import { oceanPath, SYSTEM_DIR } from "@ocean/core/shared/paths.js";
+import { resolveTaskReference } from "@ocean/core/shared/task-reference.js";
+function objective(body) {
+    const match = /^## Objective\s*\n([\s\S]*?)(?=^## |$(?![\s\S]))/m.exec(body);
+    return match ? match[1].trim() : "";
+}
+async function installedProfiles() {
+    return (await readdir(oceanPath(SYSTEM_DIR, "profiles")).catch(() => []))
+        .filter((name) => name.endsWith(".json"))
+        .map((name) => name.slice(0, -".json".length));
+}
+export async function selectProfileForTask(ref, options = {}) {
+    const location = await resolveTaskReference(ref, { cwd: options.cwd });
+    const source = await readFile(location.file, "utf8");
+    const fields = parseFrontmatter(source);
+    const suggested = suggestProfile({
+        id: location.id,
+        title: fields.title ?? "",
+        kind: fields.kind ?? fields.type,
+        class: fields.class,
+        risk: fields.risk,
+        objective: objective(source),
+    }, await installedProfiles());
+    const selection = {
+        task: location.id,
+        profile: options.override ?? suggested.profile,
+        override: Boolean(options.override),
+        suggested,
+    };
+    const log = oceanPath(SYSTEM_DIR, "state", "profiles", "selections.jsonl");
+    await mkdir(path.dirname(log), { recursive: true, mode: 0o700 });
+    await appendFile(log, `${JSON.stringify({ ts: new Date().toISOString(), ...selection })}\n`, { mode: 0o600 });
+    return selection;
+}
+//# sourceMappingURL=profile-suggestion.js.map

package/dist/application/profiles/profile-upgrade-service.js

@@ -0,0 +1,208 @@
+import { createHash } from "node:crypto";
+import { mkdir, readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { upgradeProfile } from "@ocean/core/domain/profiles/profile-upgrade.js";
+import { atomicWrite, withFileLock } from "@ocean/core/shared/fs-utils.js";
+import { oceanPath, SYSTEM_DIR } from "@ocean/core/shared/paths.js";
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+export function profilesDir() {
+    return oceanPath(SYSTEM_DIR, "profiles");
+}
+// Backups and the manifest live beside the profiles, under a name no profile can have.
+function upgradeDir() {
+    return path.join(profilesDir(), ".upgrade");
+}
+function manifestFile() {
+    return path.join(upgradeDir(), "manifest.json");
+}
+async function readManifest() {
+    try {
+        return JSON.parse(await readFile(manifestFile(), "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+async function isDirectory(target) {
+    return (await stat(target).catch(() => null))?.isDirectory() ?? false;
+}
+export async function planProfileUpgrade() {
+    const dir = profilesDir();
+    const names = (await readdir(dir).catch(() => [])).sort();
+    const entries = [];
+    for (const entry of names) {
+        const full = path.join(dir, entry);
+        if (entry.startsWith("."))
+            continue;
+        if (entry.endsWith(".json")) {
+            const name = entry.slice(0, -".json".length);
+            if (await isDirectory(path.join(dir, name))) {
+                entries.push({
+                    name,
+                    file: full,
+                    status: "collision",
+                    issues: [`both ${entry} and the legacy directory ${name}/ exist`],
+                });
+                continue;
+            }
+            const source = await readFile(full, "utf8");
+            let raw;
+            try {
+                raw = JSON.parse(source);
+            }
+            catch {
+                // The parser's message quotes the file around the error; it is not repeated.
+                entries.push({
+                    name,
+                    file: full,
+                    status: "rejected",
+                    issues: ["invalid JSON"],
+                });
+                continue;
+            }
+            const result = upgradeProfile(raw);
+            const declared = raw?.name;
+            if (result.status !== "rejected" && declared !== name) {
+                entries.push({
+                    name,
+                    file: full,
+                    status: "rejected",
+                    issues: [`declares name "${String(declared)}", expected "${name}"`],
+                });
+                continue;
+            }
+            if (result.status === "upgrade") {
+                const next = `${JSON.stringify(result.profile, null, 2)}\n`;
+                entries.push({
+                    name,
+                    file: full,
+                    status: "upgrade",
+                    changes: result.changes,
+                    v1Sha256: sha256(source),
+                    v2Sha256: sha256(next),
+                    next,
+                });
+            }
+            else if (result.status === "rejected")
+                entries.push({
+                    name,
+                    file: full,
+                    status: "rejected",
+                    issues: result.issues,
+                });
+            else
+                entries.push({ name, file: full, status: "current" });
+        }
+        else if ((await isDirectory(full)) && !names.includes(`${entry}.json`))
+            entries.push({
+                name: entry,
+                file: full,
+                status: "legacy-directory",
+                issues: ["legacy directory profiles are not upgraded; convert by hand"],
+            });
+    }
+    return entries;
+}
+// All or nothing: one rejected file or collision blocks every write. A re-run after a
+// successful apply finds every profile current and writes nothing.
+export async function applyProfileUpgrade() {
+    return withFileLock(manifestFile(), async () => {
+        const plan = await planProfileUpgrade();
+        const blocked = plan.filter((entry) => entry.status === "rejected" || entry.status === "collision");
+        if (blocked.length)
+            return { applied: [], blocked };
+        const pending = plan.filter((entry) => entry.status === "upgrade");
+        if (!pending.length)
+            return { applied: [], blocked: [] };
+        await mkdir(upgradeDir(), { recursive: true, mode: 0o700 });
+        // One manifest across every apply: a later batch adds to it, so rollback still covers
+        // profiles upgraded earlier. A profile upgraded again (after a rollback) replaces its entry.
+        const previous = await readManifest();
+        const manifest = {
+            appliedAt: new Date().toISOString(),
+            entries: (previous?.entries ?? []).filter((entry) => !pending.some((item) => item.name === entry.name)),
+        };
+        // Every v1 copy is written and verified before any profile is replaced.
+        for (const entry of pending) {
+            const source = await readFile(entry.file, "utf8");
+            if (sha256(source) !== entry.v1Sha256)
+                throw new Error(`${entry.name} changed during the upgrade; nothing applied`);
+            const backup = path.join(upgradeDir(), `${entry.name}.${entry.v1Sha256?.slice(0, 12)}.v1.json`);
+            await atomicWrite(backup, source, 0o600);
+            if (sha256(await readFile(backup, "utf8")) !== entry.v1Sha256)
+                throw new Error(`backup of ${entry.name} did not verify; nothing applied`);
+            manifest.entries.push({
+                name: entry.name,
+                v1Sha256: entry.v1Sha256,
+                v2Sha256: entry.v2Sha256,
+                backup: path.basename(backup),
+            });
+        }
+        await atomicWrite(manifestFile(), `${JSON.stringify(manifest, null, 2)}\n`, 0o600);
+        for (const entry of pending)
+            await atomicWrite(entry.file, entry.next, 0o600);
+        return { applied: pending.map((entry) => entry.name), blocked: [] };
+    });
+}
+// Restores each v1 copy, but only over a file still exactly as the upgrade wrote it; a
+// profile edited since then is reported and left alone.
+export async function rollbackProfileUpgrade() {
+    return withFileLock(manifestFile(), async () => {
+        const manifest = await readManifest();
+        if (!manifest)
+            throw new Error("No profile upgrade to roll back");
+        const restored = [];
+        const skipped = [];
+        for (const entry of manifest.entries) {
+            const file = path.join(profilesDir(), `${entry.name}.json`);
+            const current = await readFile(file, "utf8").catch(() => null);
+            if (current === null || sha256(current) === entry.v1Sha256) {
+                if (current !== null)
+                    restored.push(entry.name);
+                else
+                    skipped.push({ name: entry.name, reason: "profile file is missing" });
+                continue;
+            }
+            if (sha256(current) !== entry.v2Sha256) {
+                skipped.push({ name: entry.name, reason: "edited since the upgrade" });
+                continue;
+            }
+            const backup = await readFile(path.join(upgradeDir(), entry.backup), "utf8");
+            if (sha256(backup) !== entry.v1Sha256) {
+                skipped.push({ name: entry.name, reason: "backup does not verify" });
+                continue;
+            }
+            await atomicWrite(file, backup, 0o600);
+            restored.push(entry.name);
+        }
+        return { restored, skipped };
+    });
+}
+// Loads every profile the way a run would and reports each failure by name. Messages are
+// validation errors, which name fields, never values from a credential check.
+export async function validateProfiles(load) {
+    const dir = profilesDir();
+    const names = new Set();
+    for (const entry of await readdir(dir).catch(() => [])) {
+        if (entry.startsWith("."))
+            continue;
+        if (entry.endsWith(".json"))
+            names.add(entry.slice(0, -".json".length));
+        else if (await isDirectory(path.join(dir, entry)))
+            names.add(entry);
+    }
+    const results = [];
+    for (const name of [...names].sort()) {
+        try {
+            const profile = await load(name);
+            results.push({ name, ok: true, schemaVersion: profile.schemaVersion });
+        }
+        catch (error) {
+            results.push({ name, ok: false, error: error.message });
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=profile-upgrade-service.js.map