@kisev/agentomatic 11.0.0-dev.48.gf6e4f0e086aa → 11.0.0-dev.49.gf74dc1d4e538

package/README.md

@@ -61,21 +61,26 @@ outdated facts by key, and archives every pre-image.
 
 ## Project Install
 
-Install the package in the repository's npm project and preview the managed
-assets:
+Run the installer from the repository root (add `--global` for the global
+scope); the confirmed install also provisions the persistent npm dependency:
 
 ```shell
-npm install --save-exact @kisev/agentomatic
 npx --yes @kisev/agentomatic@latest install --dry-run
 ```
 
-Run the exact confirmation command printed by the preview. If the selected
+The confirmed install pins the executing version into the nearest npm project;
+global installs own `~/.config/opencode` and create its `package.json` when
+needed. Offline setups can provision the dependency by hand first:
+`npm install --save-exact @kisev/agentomatic`, then run
+`npx agentomatic install --dry-run` from that project so the executing version
+matches the installed package. Run the exact confirmation command
+printed by the preview. If the selected
 assets need core integration, connect the package into the user-owned OpenCode
 configuration yourself or through the confirmed `config` command, which merges
 the `plugin` entry while preserving existing entries:
 
 ```shell
-npx --yes @kisev/agentomatic@latest config --global --dry-run
+npx agentomatic config --global --dry-run
 ```
 
 ```json

package/README.ru.md

@@ -64,21 +64,26 @@ Memomatic - персональная обучающая память по мот
 
 ## Установка в проект
 
-Установите пакет в npm-проект репозитория и предварительно просмотрите
-управляемые файлы:
+Запустите установщик из корня репозитория (добавьте `--global` для глобальной
+области); подтверждённая установка также пропишет постоянную npm-зависимость:
 
 ```shell
-npm install --save-exact @kisev/agentomatic
 npx --yes @kisev/agentomatic@latest install --dry-run
 ```
 
+Подтверждённая установка закрепляет исполняемую версию в ближайшем npm-проекте;
+глобальная установка владеет `~/.config/opencode` и при необходимости создаёт
+там `package.json`. В офлайн-окружении зависимость можно поставить вручную:
+`npm install --save-exact @kisev/agentomatic`, затем запустить
+`npx agentomatic install --dry-run` из этого проекта, чтобы версия исполнения
+совпадала с установленным пакетом.
 Выполните точную команду подтверждения, которую выведет предварительный просмотр.
 Если для выбранных файлов нужна основная интеграция, подключите пакет в
 пользовательскую конфигурацию OpenCode вручную или подтвержденной командой
 `config`, которая добавляет запись `plugin` с сохранением существующих записей:
 
 ```shell
-npx --yes @kisev/agentomatic@latest config --global --dry-run
+npx agentomatic config --global --dry-run
 ```
 
 ```json

package/dist/cli.js

@@ -67,6 +67,11 @@ function parseOptions(values) {
                 throw new InstallerError("invalid_input", "--json may be supplied once");
             options.json = true;
         }
+        else if (value === "--no-dependency") {
+            if (options.noDependency)
+                throw new InstallerError("invalid_input", "--no-dependency may be supplied once");
+            options.noDependency = true;
+        }
         else if (["--commands", "--skill-commands", "--agents", "--plugins"].includes(value)) {
             const raw = values[++index];
             if (!raw)
@@ -258,6 +263,7 @@ function contextualHelp(arguments_) {
             ["--global", "Use global scope; project scope is the default."],
             ["--dry-run", "Preview operations and issue a one-time confirmation digest."],
             ["--confirm <digest>", "Apply the exact unexpired preview."],
+            ["--no-dependency", "Skip provisioning the persistent npm dependency for the core plugin."],
             ["--commands <list|none>", "Select installed-skill adapters."],
             ["--skill-commands <list|none>", "Select installed-skill adapters."],
             ["--agents <list|none>", "Select fixed agents."],
@@ -940,7 +946,7 @@ async function run(arguments_) {
             : undefined;
         requireConfirmationMode(options);
         if (options.dryRun) {
-            const plan = await preview(action, options.scope, process.cwd(), undefined, selection);
+            const plan = await preview(action, options.scope, process.cwd(), undefined, selection, !options.noDependency);
             if (options.json)
                 process.stdout.write(`${JSON.stringify({ status: "ok", applied: false, requires_restart: plan.requires_restart, plan }, null, 2)}\n`);
             else
@@ -950,13 +956,14 @@ async function run(arguments_) {
                         action,
                         ...scopeArguments(options.scope),
                         ...(action === "install" ? selectionArguments(plan.selection) : []),
+                        ...(options.noDependency ? ["--no-dependency"] : []),
                         "--confirm",
                         plan.digest,
                     ]),
                 }));
         }
         else {
-            const plan = await apply(action, options.scope, options.confirm, process.cwd(), undefined, {}, selection);
+            const plan = await apply(action, options.scope, options.confirm, process.cwd(), undefined, {}, selection, !options.noDependency);
             if (options.json)
                 process.stdout.write(`${JSON.stringify({ status: "ok", applied: true, requires_restart: plan.requires_restart, plan }, null, 2)}\n`);
             else

package/dist/installer.d.ts

@@ -1,6 +1,7 @@
 import { LifecycleError, type FileMutation, type Scope, type SupersededPlan, type TransactionOptions } from "./lifecycle.js";
 import { CATALOG } from "./catalog.js";
 import { type FixedAgentRole } from "./agent-profiles.js";
+import { type DependencyPlan, type DependencyRunner } from "./self-install.js";
 export type { Scope } from "./lifecycle.js";
 export type Action = "install" | "uninstall";
 export type Operation = "create" | "update" | "remove" | "unchanged" | "missing" | "conflict" | "archive-pending";
@@ -25,6 +26,9 @@ export type Plan = {
     package_version: string;
     selection: InstallerSelection;
     operations: PlanItem[];
+    dependency?: DependencyPlan & {
+        applied?: "changed" | "unchanged" | "skipped";
+    };
     plan_digest: string;
     confirmation_digest?: string;
     superseded_plan?: SupersededPlan;
@@ -51,6 +55,8 @@ export declare function normalizeSelection(value?: Partial<InstallerSelection>):
 export declare class InstallerError extends LifecycleError {
 }
 export declare function archiveMutations(candidates: readonly ArchiveCandidate[], scope: Scope, cwd: string, home: string, sourceVersion: string): Promise<FileMutation[]>;
-export declare function preview(action: Action, scope: Scope, cwd?: string, home?: string, selection?: Partial<InstallerSelection>): Promise<Plan>;
-export declare function apply(action: Action, scope: Scope, confirmationDigest: string, cwd?: string, home?: string, options?: TransactionOptions, selection?: Partial<InstallerSelection>): Promise<Plan>;
+export declare function preview(action: Action, scope: Scope, cwd?: string, home?: string, selection?: Partial<InstallerSelection>, provisionDependency?: boolean): Promise<Plan>;
+export declare function apply(action: Action, scope: Scope, confirmationDigest: string, cwd?: string, home?: string, options?: TransactionOptions & {
+    dependencyRunner?: DependencyRunner;
+}, selection?: Partial<InstallerSelection>, provisionDependency?: boolean): Promise<Plan>;
 export declare function result(plan: Plan, applied: boolean): string;

package/dist/installer.js

@@ -8,6 +8,7 @@ import { applyTransaction, archiveRoot, consumeReceipt, deploymentRoot, destinat
 import { CATALOG } from "./catalog.js";
 import { FIXED_AGENT_ROLES } from "./agent-profiles.js";
 import { readPackageVersion } from "./package-metadata.js";
+import { ensureDependency, planDependency, } from "./self-install.js";
 const PACKAGE_NAME = "@kisev/agentomatic";
 const MANIFEST_NAME = ".agentomatic-manifest.json";
 const LEGACY_MANIFEST_NAME = ".skills-opencode-manifest.json";
@@ -324,7 +325,7 @@ function asLegacy(manifest) {
         ? manifest
         : undefined;
 }
-async function build(action, scope, cwd = process.cwd(), home = homedir(), requestedSelection) {
+async function build(action, scope, cwd = process.cwd(), home = homedir(), requestedSelection, provisionDependency = true) {
     const root = deploymentRoot(scope, cwd, home);
     const owned = await currentManifest(root);
     const selection = normalizeSelection(requestedSelection ??
@@ -346,6 +347,9 @@ async function build(action, scope, cwd = process.cwd(), home = homedir(), reque
         }
         : undefined;
     const profiles = await buildAgentProfilePlan({ action }, scope, cwd, home, legacyRecord, selection.agents);
+    const dependency = action === "install" && provisionDependency && selection.core_activation
+        ? planDependency(scope, cwd, home)
+        : undefined;
     const operations = profiles.plan.operations.map((item) => ({
         path: item.path,
         operation: item.operation,
@@ -602,6 +606,7 @@ async function build(action, scope, cwd = process.cwd(), home = homedir(), reque
         package_version: packageVersion(),
         selection,
         operations: sorted,
+        ...(dependency ? { dependency } : {}),
         requires_restart: (action === "install" && owned.manifest?.package_version !== packageVersion()) ||
             profiles.plan.requires_restart ||
             mutations.some((item) => item.path.startsWith("agents/") ||
@@ -616,7 +621,7 @@ async function build(action, scope, cwd = process.cwd(), home = homedir(), reque
         profiles,
     };
 }
-export async function preview(action, scope, cwd = process.cwd(), home = homedir(), selection) {
+export async function preview(action, scope, cwd = process.cwd(), home = homedir(), selection, provisionDependency = true) {
     // Infrastructure normalization like stale-lock reclamation: idempotent,
     // preserves every legacy byte, and never touches user configuration.
     await migrateLegacyNamespaces(home);
@@ -626,7 +631,7 @@ export async function preview(action, scope, cwd = process.cwd(), home = homedir
         return await withLifecycleLock(stateRoot, async () => {
             if (await recoverTransaction(root, stateRoot, [archiveRoot(scope, cwd, home)]))
                 throw new InstallerError("recovered_transaction", "Recovered an interrupted transaction; request a fresh plan");
-            const built = await build(action, scope, cwd, home, selection);
+            const built = await build(action, scope, cwd, home, selection, provisionDependency);
             const receipt = await saveReceipt(stateRoot, `installer:${action}`, scope, root, { plan_digest: built.plan.digest }, Date.now(), built.plan.digest);
             return {
                 ...built.plan,
@@ -646,7 +651,8 @@ export async function preview(action, scope, cwd = process.cwd(), home = homedir
         throw error;
     }
 }
-export async function apply(action, scope, confirmationDigest, cwd = process.cwd(), home = homedir(), options = {}, selection) {
+export async function apply(action, scope, confirmationDigest, cwd = process.cwd(), home = homedir(), options = {}, selection, provisionDependency = true) {
+    const { dependencyRunner, ...transactionOptions } = options;
     const stateRoot = lifecycleRoot(scope, cwd, home);
     const root = deploymentRoot(scope, cwd, home);
     await migrateLegacyNamespaces(home);
@@ -661,7 +667,7 @@ export async function apply(action, scope, confirmationDigest, cwd = process.cwd
                 scope,
                 root,
             }));
-            const built = await build(action, scope, cwd, home, selection);
+            const built = await build(action, scope, cwd, home, selection, provisionDependency);
             const savedPlanDigest = receipt.plan_digest ??
                 receipt.digest;
             if (built.plan.digest !== savedPlanDigest)
@@ -676,7 +682,7 @@ export async function apply(action, scope, confirmationDigest, cwd = process.cwd
                 built.plan.operations.some((item) => item.operation === "conflict"))
                 throw new InstallerError("conflict", "Installer plan contains managed drift");
             await applyTransaction(root, stateRoot, built.mutations, {
-                ...options,
+                ...transactionOptions,
                 validateFinal: async () => {
                     await options.validateFinal?.();
                     await validateBuiltAgentProfilePlan(built.profiles);
@@ -694,7 +700,14 @@ export async function apply(action, scope, confirmationDigest, cwd = process.cwd
                     }
                 },
             });
-            return { ...built.plan, digest: confirmationDigest };
+            const dependencyOutcome = action === "install" && built.plan.dependency
+                ? await ensureDependency(built.plan.dependency, dependencyRunner)
+                : undefined;
+            return {
+                ...built.plan,
+                digest: confirmationDigest,
+                ...(dependencyOutcome ? { dependency: dependencyOutcome } : {}),
+            };
         });
     }
     catch (error) {

package/dist/self-install.d.ts

@@ -0,0 +1,24 @@
+import { LifecycleError } from "@kisev/safe-fs";
+export declare const SELF_PACKAGE_NAME = "@kisev/agentomatic";
+export type DependencyRunner = (command: string, args: string[], options: {
+    cwd: string;
+    timeout: number;
+}) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export type DependencyPlan = {
+    dir: string | null;
+    name: string;
+    version: string;
+    status: "install" | "update" | "satisfied" | "manual";
+    package_json: "present" | "create" | "missing";
+    reason?: string;
+};
+export declare class SelfInstallError extends LifecycleError {
+}
+export declare function owningProjectDir(scope: "project" | "global", cwd?: string, home?: string): string | null;
+export declare function planDependency(scope: "project" | "global", cwd?: string, home?: string, version?: string): DependencyPlan;
+export declare function ensureDependency(plan: DependencyPlan, runner?: DependencyRunner): Promise<DependencyPlan & {
+    applied: "changed" | "unchanged" | "skipped";
+}>;

package/dist/self-install.js

@@ -0,0 +1,100 @@
+import { execFile } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { LifecycleError, writeAtomic } from "@kisev/safe-fs";
+import { requirePackageVersion } from "./package-metadata.js";
+const execFileAsync = promisify(execFile);
+export const SELF_PACKAGE_NAME = "@kisev/agentomatic";
+const NPM_INSTALL_TIMEOUT_MS = 180_000;
+export class SelfInstallError extends LifecycleError {
+}
+export function owningProjectDir(scope, cwd = process.cwd(), home = homedir()) {
+    if (scope === "global")
+        return join(home, ".config", "opencode");
+    let dir = resolve(cwd);
+    for (;;) {
+        if (existsSync(join(dir, "package.json")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+function readDependencyVersion(dir) {
+    try {
+        const value = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return null;
+        const dependency = value.dependencies;
+        if (!dependency || typeof dependency !== "object" || Array.isArray(dependency))
+            return null;
+        const pinned = dependency[SELF_PACKAGE_NAME];
+        return typeof pinned === "string" && pinned.length > 0 ? pinned : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function planDependency(scope, cwd = process.cwd(), home = homedir(), version = requirePackageVersion()) {
+    if (scope === "global") {
+        const dir = join(home, ".config", "opencode");
+        const hasPackageJson = existsSync(join(dir, "package.json"));
+        if (!hasPackageJson)
+            return { dir, name: SELF_PACKAGE_NAME, version, status: "install", package_json: "create" };
+        const pinned = readDependencyVersion(dir);
+        if (pinned === version)
+            return {
+                dir,
+                name: SELF_PACKAGE_NAME,
+                version,
+                status: "satisfied",
+                package_json: "present",
+            };
+        return {
+            dir,
+            name: SELF_PACKAGE_NAME,
+            version,
+            status: pinned ? "update" : "install",
+            package_json: "present",
+        };
+    }
+    const dir = owningProjectDir("project", cwd, home);
+    if (!dir)
+        return {
+            dir: null,
+            name: SELF_PACKAGE_NAME,
+            version,
+            status: "manual",
+            package_json: "missing",
+            reason: "no package.json found upward from the working directory; create an npm project or use --global",
+        };
+    const pinned = readDependencyVersion(dir);
+    if (pinned === version)
+        return { dir, name: SELF_PACKAGE_NAME, version, status: "satisfied", package_json: "present" };
+    return {
+        dir,
+        name: SELF_PACKAGE_NAME,
+        version,
+        status: pinned ? "update" : "install",
+        package_json: "present",
+    };
+}
+export async function ensureDependency(plan, runner = execFileAsync) {
+    if (plan.status === "manual" || plan.status === "satisfied")
+        return { ...plan, applied: plan.status === "satisfied" ? "unchanged" : "skipped" };
+    const dir = plan.dir;
+    if (plan.package_json === "create" && !existsSync(join(dir, "package.json"))) {
+        await writeAtomic(join(dir, "package.json"), Buffer.from('{"name":"opencode-agentomatic","private":true}\n'), 0o644);
+    }
+    try {
+        await runner("npm", ["install", "--save-exact", `${plan.name}@${plan.version}`, "--no-audit", "--no-fund"], { cwd: dir, timeout: NPM_INSTALL_TIMEOUT_MS });
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message.split("\n").slice(-6).join("\n") : "";
+        throw new SelfInstallError("npm_dependency_failed", `npm install for ${plan.name}@${plan.version} in ${dir} failed: ${detail}`);
+    }
+    return { ...plan, applied: "changed" };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kisev/agentomatic",
-  "version": "11.0.0-dev.48.gf6e4f0e086aa",
+  "version": "11.0.0-dev.49.gf74dc1d4e538",
   "description": "OpenCode integration and opt-in installer for portable Agent Skills.",
   "homepage": "https://github.com/kisev/skills#readme",
   "bugs": {
@@ -44,13 +44,13 @@
   },
   "scripts": {
     "build": "node scripts/clean-dist.mjs && tsc --project tsconfig.json && node dist/generate-assets.js",
-    "test": "node --test test/agent-profiles.test.mjs test/config-setup.test.mjs test/legacy-migration.test.mjs test/doctor.test.mjs test/memomatic-plugin.test.mjs test/package.test.mjs test/rtk.test.mjs test/stage19.test.mjs",
+    "test": "node --test test/agent-profiles.test.mjs test/config-setup.test.mjs test/legacy-migration.test.mjs test/doctor.test.mjs test/memomatic-plugin.test.mjs test/package.test.mjs test/rtk.test.mjs test/self-install.test.mjs test/stage19.test.mjs",
     "smoke": "node test/smoke.mjs",
     "pack:check": "node test/pack-allowlist.mjs"
   },
   "dependencies": {
-    "@kisev/memomatic": "1.0.0-dev.48.gf6e4f0e086aa",
-    "@kisev/safe-fs": "1.0.0-dev.48.gf6e4f0e086aa"
+    "@kisev/memomatic": "1.0.0-dev.49.gf74dc1d4e538",
+    "@kisev/safe-fs": "1.0.0-dev.49.gf74dc1d4e538"
   },
   "devDependencies": {
     "@opencode-ai/plugin": "1.18.29",