@ericsanchezok/synergy-presets 0.0.0-stage → 3.1.0

package/AGENTS.md

@@ -0,0 +1,30 @@
+# Presets Package
+
+Own complete-product source composition, cross-domain data commands and integration fixtures. Generic Bun bootstrap belongs to Agent Runtime; CLI process lifecycle belongs to CLI, and HTTP asset serving belongs to Server. Read the root [AGENTS.md](../../AGENTS.md) and [architecture ownership map](../../docs/architecture/README.md#ownership-map) before changes.
+
+- Assemble configuration, session schemas, migrations, tools, agents, routes and services explicitly before opening the shared Harness lifecycle through `PresetRuntimeHandle`. Startup seals configuration and migration registration; late imports must not partially install a capability.
+- Keep business implementations with their owning packages. Presets connects typed sources and lifecycle contributions; do not move domain algorithms into assembly or introduce package scanning.
+- Preserve the single `runCli()` parser and `synergy` command. Compose the same `createRuntimeCli` component adapters as an installed host. Full-data pack, merge and move operations belong here; Library owns its SQLite merge algorithms.
+- Source and compiled agent workers use Agent Runtime role entrypoints and the explicitly pinned component plan; never register the full foreground composition in workers. Preserve resource discovery, verified sandbox assets, cancellation, evidence failures and shutdown drainage.
+- Keep core-only tests in Harness or Local Runtime. Full API, cross-domain lifecycle and product configuration tests belong here and explicitly register their required services.
+- Preserve unloaded domain data and existing migration IDs and ledgers. Read [persistence guidance](../../.synergy/skill/change-persistence/SKILL.md) before changing upgrades, imports or data movement.
+- Full-data copies hold native directory retirement claims as well as offline Home locks, including selected folders and source removal. Copied Git relationship repair belongs to Local Runtime and must never reconnect to an uncopied source.
+- Select Browser hosting only in the Desktop composition; CLI/Web omit it. Browser backend ownership belongs to `packages/browser-runtime`; protocol contracts belong to `packages/browser-core`.
+
+Prepare native PTY assets with `bun ../../packages/local-runtime/script/build-pty.ts` before `bun test test/server/runtime-websocket-shutdown.test.ts`. CI supplies the verified native build artifact.
+
+Run `bun run typecheck`, affected tests and `bun run test:coverage` from this package. The shared testing orchestrator injects a positive isolated-home marker into every child; never use raw parallel coverage. Model fixtures belong to `packages/testing/fixtures/models-api.json`.
+
+`script/acceptance.ts` owns opt-in local joint acceptance through `plan/run/resume/report`; its behavioral regressions live in `test/acceptance`. Keep real-provider calls outside CI, retain failed attempts and unknown accounting, and require independently verified evidence before reporting coverage.
+
+Run manual startup and CLI checks with an isolated `SYNERGY_HOME` using `develop-synergy`. Never restart or modify the active instance. For releases, verify full assets and an installed tarball outside the repository; source resolution alone cannot prove the package is complete.
+
+Review the owning Skill for CLI, persistence, execution, API, Browser or Channel changes. Regenerate API contracts with the root `./script/generate.ts` and command documentation with `bun script/gen/gen-cli-reference.ts` when those public contracts change.
+
+`bun run build` compiles workspace modules into `dist/modules`. Use the package-owned `bun script/build.ts --single --skip-install` for a local executable; release tooling selects its target matrix through that same explicit binary entry.
+
+Consume declarative core/full/Web/Desktop selections from Plugin Host’s public `installation/catalog` leaf. Full includes backend components, HTTP and authoring tools; Web adds the application payload and Desktop adds its signed shell. `dataManagement()` contributes cross-domain data commands through the same component API. Source development also selects the local Web assets explicitly.
+
+Public `PresetRuntimeHandle` embeds the backend without repository paths. Callers explicitly select Web assets with `webAppDirectory`; only the source CLI selects repository assets. Publish the active configuration schema through the shared lifecycle instead of copying an executable-adjacent schema. Verify both API-only and explicit-Web embedding outside the repository.
+
+Feature selection uses Util’s shared resolver before registration. Full contract generation explicitly includes all declarations. Offline maintenance loads dormant owner data contributions without runtime activation; follow [develop-feature](../../.synergy/skill/develop-feature/SKILL.md).

package/README.md

@@ -1,3 +1,75 @@
-# Temporary Holding Version
+# Synergy
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The core runtime for [Synergy](https://github.com/SII-Holos/synergy) — an AI agent platform built by the Holos team.
+
+## What's in this package
+
+This is the engine behind Synergy. It provides:
+
+- **Server runtime** — a stateless server that clients connect to over HTTP
+- **CLI** — `synergy start`, `synergy web`, `synergy send`, and operational commands for sessions, config, identity, and more
+- **Agent system** — built-in configurable agents for coding, research, writing, orchestration, and review
+- **Sessions** — persistent conversation management with recall and context
+- **Tools** — file operations, search, process management, web access, and extensible tool definitions
+- **MCP integration** — connect external tool ecosystems via the Model Context Protocol
+- **Provider support** — multi-provider LLM integration (OpenAI, Anthropic, Google, and many others)
+- **Config system** — layered configuration with global, project, and runtime scopes
+- **Library** — long-term memory and knowledge infrastructure
+- **Notes, Agenda, Channels** — persistent notes, scheduled automation, and messaging integrations
+
+## Installation
+
+```bash
+npm install @ericsanchezok/synergy
+# or
+bun add @ericsanchezok/synergy
+```
+
+## Quick start
+
+Start the background service:
+
+```bash
+synergy start
+```
+
+Then open the web interface or send a one-off message:
+
+```bash
+synergy web
+synergy send "summarize this project"
+```
+
+Check on the service at any time:
+
+```bash
+synergy status
+synergy logs
+```
+
+## Session worktrees
+
+For Git-backed scopes, use the built-in `/worktree` session command to isolate work in a project-local Git worktree:
+
+```text
+/worktree list
+/worktree new add-rate-limit
+/worktree enter add-rate-limit
+/worktree status
+/worktree leave
+/worktree remove add-rate-limit --force
+```
+
+Synergy-created worktrees live in `.synergy/worktrees/`, and metadata lives in `.synergy/worktrees/.registry/`. New worktrees can run project-local setup from `.synergy/worktree-setup.jsonc` and machine-local overrides from `.synergy/worktree-setup.local.jsonc`.
+
+See the main repository README for the full worktree workflow, setup file format, and cleanup rules.
+
+## Documentation
+
+Local architecture acceptance uses `bun run acceptance --help` from this package. `plan` requires explicit scenario IDs and an external private evidence directory; `run` uses frozen settings, `resume` leaves completed or interrupted attempts untouched unless a retry is explicitly named with a reason, and `report` independently checks recorded evidence. Live scenarios make real provider requests. See the [testing workflow](../../.synergy/skill/testing-guide/SKILL.md#local-joint-acceptance).
+
+For full setup instructions, configuration, development workflow, and the complete package map, see the [main repository README](https://github.com/SII-Holos/synergy).
+
+## License
+
+MIT

package/dist/modules/access/index.js

@@ -0,0 +1,21 @@
+export var Access;
+(function (Access) {
+    function normalizeUrl(value) {
+        return value.replace(/\/+$/, "");
+    }
+    Access.normalizeUrl = normalizeUrl;
+    function fromServerUrl(serverUrl) {
+        const attachUrl = normalizeUrl(serverUrl);
+        return {
+            attachUrl,
+        };
+    }
+    Access.fromServerUrl = fromServerUrl;
+    function frontendEnv(serverUrl) {
+        const descriptor = fromServerUrl(serverUrl);
+        return {
+            VITE_SYNERGY_SERVER_URL: descriptor.attachUrl,
+        };
+    }
+    Access.frontendEnv = frontendEnv;
+})(Access || (Access = {}));

package/dist/modules/cli/data/index.js

@@ -0,0 +1,31 @@
+import { cmd } from "@ericsanchezok/synergy-util/cli-command";
+import { createDataCommand } from "@ericsanchezok/synergy-cli/cli/cmd/data";
+import { DataMoveCommand } from "./move.js";
+import { DataPackCommand } from "./pack.js";
+import { DataMergeCommand } from "./merge.js";
+export const commands = [DataMoveCommand, DataPackCommand, DataMergeCommand];
+export const DataCommand = createDataCommand(commands);
+/** Backward-compatible alias: `synergy migrate` → `synergy data move` */
+export const MigrateCommand = cmd({
+    command: "migrate",
+    describe: "move synergy data to a new location (alias for 'data move')",
+    builder: (yargs) => yargs
+        .option("target", { type: "string", describe: "target directory path" })
+        .option("remove-original", {
+        type: "boolean",
+        default: false,
+        describe: "remove original data after successful move",
+    })
+        .option("dry-run", {
+        type: "boolean",
+        default: false,
+        describe: "show plan without executing",
+    }),
+    handler: async (args) => {
+        const target = args.target;
+        const removeOriginal = args.removeOriginal;
+        const dryRun = args.dryRun;
+        const { executeMove } = await import("@ericsanchezok/synergy-presets/cli/data/move");
+        await executeMove({ target, removeOriginal, dryRun });
+    },
+});

package/dist/modules/cli/data/merge.js

@@ -0,0 +1,251 @@
+import { logo } from "@ericsanchezok/synergy-cli/branding";
+import { getLibraryInfo, resolveLibraryDB, mergeLibraryDB, } from "@ericsanchezok/synergy-library/cli/data";
+import { DataTransfer } from "./transfer.js";
+import fs from "fs/promises";
+import path from "path";
+import os from "os";
+import * as prompts from "@clack/prompts";
+import { cmd } from "@ericsanchezok/synergy-util/cli-command";
+import { UI } from "@ericsanchezok/synergy-util/terminal";
+import { archiveExclusions, CATEGORIES, scanCategories, formatSize, shortenPath, dirExists, copyDirSkipExisting, dataRoot, } from "@ericsanchezok/synergy-cli/cli/cmd/data/shared";
+export const DataMergeCommand = cmd({
+    command: "merge <source>",
+    describe: "merge data from another synergy directory or zip archive",
+    builder: (yargs) => yargs.positional("source", {
+        type: "string",
+        describe: "source directory path, zip, or tar.gz archive",
+        demandOption: true,
+    }),
+    handler: async (args) => {
+        const sourceArg = args.source;
+        const targetRoot = dataRoot();
+        UI.empty();
+        UI.println(logo("  "));
+        UI.empty();
+        prompts.intro("Merge Synergy Data");
+        // Prepare source
+        const source = await prepareSource(sourceArg);
+        if (!source) {
+            prompts.outro("Merge aborted");
+            return;
+        }
+        try {
+            const srcCatStats = await scanCategories(source.dataDir);
+            const tgtCatStats = await scanCategories(targetRoot);
+            let srcTotal = 0;
+            for (const stats of srcCatStats.values())
+                srcTotal += stats.size;
+            prompts.log.info(`Source: ${shortenPath(source.path)} (${formatSize(srcTotal)})`);
+            prompts.log.info(`Target: ${shortenPath(targetRoot)} (current)`);
+            // Check library compatibility from manifest or direct scan
+            const srcLibrary = await resolveLibraryDB(source.dataDir);
+            const tgtLibrary = path.join(targetRoot, "data", "library.db");
+            let srcLibraryInfo = await getLibraryInfo(srcLibrary);
+            let libraryStrategy = "text_only";
+            // If we have a manifest, show it
+            if (source.manifest) {
+                const m = source.manifest;
+                prompts.log.info(`Archive created: ${m.createdAt}`);
+                const manifestLibrary = m.library ?? m.engram;
+                if (manifestLibrary) {
+                    prompts.log.info(`Source library: ${manifestLibrary.dimensions ?? "no"} dimensions${manifestLibrary.embeddingModel ? ` (${manifestLibrary.embeddingModel})` : ""}, ${manifestLibrary.memoryCount} memories`);
+                }
+            }
+            // Step 1: Select categories
+            const selectable = CATEGORIES.filter((c) => !c.required);
+            const selected = await prompts.multiselect({
+                message: "What should be merged? (Space to toggle, Enter to confirm)",
+                options: selectable.map((cat) => ({
+                    value: cat.key,
+                    label: cat.label,
+                    hint: formatSize(srcCatStats.get(cat.key)?.size ?? 0),
+                })),
+                initialValues: selectable.filter((c) => c.defaultValue).map((c) => c.key),
+                required: false,
+            });
+            if (prompts.isCancel(selected)) {
+                prompts.cancel("Cancelled");
+                return;
+            }
+            const selectedKeys = new Set([
+                ...selected,
+                ...CATEGORIES.filter((c) => c.required).map((c) => c.key),
+            ]);
+            const selectedCategories = CATEGORIES.filter((c) => selectedKeys.has(c.key));
+            // Step 2: Confirm
+            const confirm = await prompts.confirm({
+                message: `Merge data into ${shortenPath(targetRoot)}?`,
+                initialValue: true,
+            });
+            if (confirm !== true || prompts.isCancel(confirm)) {
+                prompts.cancel("Cancelled");
+                return;
+            }
+            // Step 3: Handle library dimension mismatch
+            if (selectedKeys.has("core") && srcLibraryInfo.exists) {
+                const tgtLibraryInfo = await getLibraryInfo(tgtLibrary);
+                if (tgtLibraryInfo.exists &&
+                    srcLibraryInfo.dimensions &&
+                    tgtLibraryInfo.dimensions &&
+                    srcLibraryInfo.dimensions !== tgtLibraryInfo.dimensions) {
+                    prompts.log.warn("Vector dimension mismatch:");
+                    prompts.log.info(`  Source: ${srcLibraryInfo.dimensions}d${srcLibraryInfo.embeddingModel ? ` (${srcLibraryInfo.embeddingModel})` : ""}`);
+                    prompts.log.info(`  Target: ${tgtLibraryInfo.dimensions}d${tgtLibraryInfo.embeddingModel ? ` (${tgtLibraryInfo.embeddingModel})` : ""}`);
+                    const choice = await prompts.select({
+                        message: "How should library data be handled?",
+                        options: [
+                            {
+                                value: "text_only",
+                                label: "Merge text only, discard source vectors",
+                                hint: "Source memories added without vector search until re-embedded",
+                            },
+                            { value: "skip", label: "Skip library entirely", hint: "Source memories are not imported" },
+                            {
+                                value: "replace_vectors",
+                                label: "Replace: use source vectors, drop target vectors",
+                                hint: "Your existing memories lose vector search",
+                            },
+                        ],
+                    });
+                    if (prompts.isCancel(choice)) {
+                        prompts.cancel("Cancelled");
+                        return;
+                    }
+                    libraryStrategy = choice;
+                }
+                else {
+                    libraryStrategy = "text_only";
+                }
+            }
+            await using homes = await DataTransfer.lockHomes([source.dataDir, targetRoot]);
+            // Step 4: Execute merge
+            UI.empty();
+            const errors = [];
+            let libraryMerged = false;
+            for (const cat of selectedCategories) {
+                for (const subdir of cat.subdirs) {
+                    const src = path.join(source.dataDir, subdir);
+                    const dst = path.join(targetRoot, subdir);
+                    if (!(await dirExists(src)))
+                        continue;
+                    // Special: library.db merge
+                    if (subdir === "data" && libraryStrategy !== "skip" && !libraryMerged) {
+                        const targetLibraryExists = await dirExists(tgtLibrary);
+                        if (targetLibraryExists && srcLibraryInfo.exists) {
+                            const librarySpinner = prompts.spinner();
+                            librarySpinner.start("Merging library.db...");
+                            try {
+                                const result = await mergeLibraryDB(srcLibrary, tgtLibrary, libraryStrategy);
+                                librarySpinner.stop(`Library: ${result.memoriesMerged} memories merged, ${result.experiencesMerged} experiences merged${result.memoriesSkipped > 0 ? `, ${result.memoriesSkipped} duplicates skipped` : ""}`);
+                                libraryMerged = true;
+                            }
+                            catch (e) {
+                                librarySpinner.error("Failed to merge library.db");
+                                errors.push(`library.db: ${e instanceof Error ? e.message : String(e)}`);
+                            }
+                        }
+                    }
+                    const spinner = prompts.spinner();
+                    spinner.start(`Merging ${subdir}/...`);
+                    try {
+                        const result = subdir === "data"
+                            ? await DataTransfer.merge(source.dataDir, targetRoot)
+                            : await copyDirSkipExisting(src, dst, (p) => {
+                                const pct = Math.round(((p.copied + p.skipped) / p.total) * 100);
+                                spinner.message(`Merging ${subdir}/ ${pct}% — ${shortenPath(p.currentFile)}`);
+                            }, undefined, undefined, archiveExclusions(subdir));
+                        const skippedNote = result.skipped > 0 ? ` (${result.skipped} existing files kept)` : "";
+                        spinner.stop(`Merged ${subdir}/${skippedNote}`);
+                    }
+                    catch (e) {
+                        spinner.error(`Failed to merge ${subdir}/`);
+                        errors.push(`${subdir}: ${e instanceof Error ? e.message : String(e)}`);
+                    }
+                }
+            }
+            // Report
+            UI.empty();
+            if (errors.length > 0) {
+                process.exitCode = 1;
+                prompts.log.warn("Merge completed with errors:");
+                for (const err of errors)
+                    prompts.log.error(`  ${err}`);
+            }
+            else {
+                prompts.log.success("Merge complete");
+            }
+            prompts.outro("Done");
+        }
+        finally {
+            await source.cleanup?.();
+        }
+    },
+});
+async function prepareSource(sourceArg) {
+    const resolved = path.resolve(sourceArg);
+    if (resolved.endsWith(".zip") || resolved.endsWith(".tar.gz") || resolved.endsWith(".tgz")) {
+        if (!(await dirExists(resolved))) {
+            prompts.log.error(`File not found: ${shortenPath(resolved)}`);
+            return null;
+        }
+        const spinner = prompts.spinner();
+        spinner.start("Extracting archive...");
+        try {
+            const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "synergy-merge-"));
+            const command = resolved.endsWith(".zip")
+                ? ["unzip", "-o", "-q", resolved, "-d", tmpDir]
+                : ["tar", "-xzf", resolved, "-C", tmpDir];
+            const child = Bun.spawn(command, { stdout: "ignore", stderr: "pipe" });
+            const errors = new Response(child.stderr).text();
+            if ((await child.exited) !== 0) {
+                await fs.rm(tmpDir, { recursive: true, force: true });
+                throw new Error(await errors);
+            }
+            await errors;
+            // Read manifest if it exists
+            const manifestPath = path.join(tmpDir, "manifest.json");
+            let manifest = null;
+            if (await Bun.file(manifestPath)
+                .exists()
+                .catch(() => false)) {
+                manifest = await Bun.file(manifestPath)
+                    .json()
+                    .catch(() => null);
+            }
+            spinner.stop("Archive extracted");
+            return {
+                type: "archive",
+                path: resolved,
+                dataDir: tmpDir,
+                manifest,
+                cleanup: () => fs.rm(tmpDir, { recursive: true, force: true }),
+            };
+        }
+        catch (e) {
+            spinner.error("Failed to extract archive");
+            prompts.log.error(`Extraction failed: ${e instanceof Error ? e.message : String(e)}`);
+            return null;
+        }
+    }
+    // Directory source
+    if (!(await dirExists(resolved))) {
+        prompts.log.error(`Directory not found: ${shortenPath(resolved)}`);
+        return null;
+    }
+    // Check for manifest (if merging from a previously packed+extracted dir)
+    const manifestPath = path.join(resolved, "manifest.json");
+    let manifest = null;
+    if (await Bun.file(manifestPath)
+        .exists()
+        .catch(() => false)) {
+        manifest = await Bun.file(manifestPath)
+            .json()
+            .catch(() => null);
+    }
+    return {
+        type: "directory",
+        path: resolved,
+        dataDir: resolved,
+        manifest,
+    };
+}