@cardor/agent-harness-kit 1.10.1 → 1.10.3

package/README.md

@@ -142,7 +142,7 @@ Then run the interactive setup inside your project:
 npx ahk init
 ```
 
-> **Local install required.** `ahk` needs to resolve your project's `agent-harness-kit.config.ts` and its dependencies relative to your project's own `node_modules`. A **global-only** install (`npm install -g @cardor/agent-harness-kit`) cannot do this reliably, so every command except `--version`/`--help` will detect a global-only install and exit with an error telling you to run `npm install --save-dev @cardor/agent-harness-kit` (or the `pnpm`/`yarn`/`bun` equivalent) in your project root.
+> **Local install recommended.** The generated `agent-harness-kit.config.ts` uses `import type`, which is erased at compile time, so `ahk` no longer needs to resolve the package from your project's `node_modules` at runtime. If it detects a **global-only** install (`npm install -g @cardor/agent-harness-kit`), it prints a non-blocking warning recommending `npm install --save-dev @cardor/agent-harness-kit` (or the `pnpm`/`yarn`/`bun` equivalent) — the command still runs and exits normally either way. This is only about keeping the CLI version pinned and reproducible across your team and CI, not a functional requirement.
 >
 > This check also works with **Yarn Berry (PnP)** projects, which never create a `node_modules` folder — `ahk` detects `.pnp.cjs`/`.pnp.loader.mjs` and falls back to checking that the package is declared in `package.json` instead of requiring a `node_modules` entry.
 
@@ -184,15 +184,7 @@ For Claude Code and Codex CLI (not OpenCode), you'll also be asked whether to pe
 
 Regardless of scope, `.harness/storage-state.json` is always written to the project — it records the *actual* current storage state (`scope`, `projectId`, `dbType`, `migratedAt`), separate from the *desired* state declared in the config file.
 
-When `--storage-scope global` is chosen, `ahk init` also synchronizes your provider's agent and skill files into your home directory (in addition to the project-local files it always writes), so subsequent `ahk init --storage-scope global` runs in *other* projects on the same machine can reuse them instead of re-scaffolding:
-
-| Provider      | Global agents dir           | Global skills dir            |
-| ------------- | ---------------------------- | ----------------------------- |
-| `claude-code` | `~/.claude/agents/`          | `~/.claude/skills/`           |
-| `codex-cli`   | `~/.codex/agents/`           | `~/.agents/skills/` (separate namespace from `~/.codex/agents`) |
-| `opencode`    | `~/.config/opencode/agents/` | `~/.config/opencode/skills/`  |
-
-This sync is idempotent and non-destructive: it only creates files that are missing. If everything is already present, `ahk init` prints a message and skips; if only some files are missing, it creates just those and reports what was added. Files it detects as already customized/outdated are left untouched (same "preserve, don't overwrite" rule used for project-local agent files).
+Agent and skill files always live in the project tree, regardless of storage scope — `--storage-scope` only affects where the harness DB lives.
 
 ```bash
 ahk init
@@ -522,9 +514,9 @@ The `tasks` table includes an `updated_at` timestamp column, set on creation and
 Everything in the config file is yours to change:
 
 ```ts
-import { defineHarness } from '@cardor/agent-harness-kit'
+import type { HarnessConfig } from '@cardor/agent-harness-kit'
 
-export default defineHarness({
+const config: HarnessConfig = {
   project: {
     name: 'My App',
     description: 'What this project does',
@@ -578,9 +570,13 @@ export default defineHarness({
     mcp: { enabled: true, port: 3742 },
     scripts: { enabled: true, outputDir: './.harness/scripts' },
   },
-})
+}
+
+export default config
 ```
 
+> `defineHarness()` is still exported for anyone who prefers the value-import form (`import { defineHarness } from '@cardor/agent-harness-kit'` + `export default defineHarness({ ... })`) — it's an identity function kept for backward compatibility, and `loadConfig()` supports both shapes.
+
 ### `health.sh`
 
 This is the most important file to implement. Agents will not start or close tasks until this script exits 0. Examples:

package/dist/cli.js

@@ -530,12 +530,9 @@ If orchestrating: Agent definition files in .claude/agents/
 function modelField(model) {
   return model ? `, model: ${JSON.stringify(model)}` : "";
 }
-function configTs(params) {
+function configObjectBody(params) {
   const models = params.models ?? {};
-  return `import { defineHarness } from '@cardor/agent-harness-kit'
-
-export default defineHarness({
-  project: {
+  return `  project: {
     name: ${JSON.stringify(params.name)},
     description: ${JSON.stringify(params.description)},
     docsPath: '${params.docsPath}',
@@ -583,64 +580,29 @@ export default defineHarness({
     mcp:     { enabled: true, port: ${params.port} },
     scripts: { enabled: true, outputDir: './.harness/scripts' },
   },
-})
 `;
 }
-var configMjs = configTs;
-function configCjs(params) {
-  const models = params.models ?? {};
-  return `const { defineHarness } = require('@cardor/agent-harness-kit')
-
-module.exports = defineHarness({
-  project: {
-    name: ${JSON.stringify(params.name)},
-    description: ${JSON.stringify(params.description)},
-    docsPath: '${params.docsPath}',
-  },
-
-  provider: '${params.provider}',
-
-  agents: {
-    lead:     { instructionsPath: null${modelField(models.lead)} },
-    explorer: { instructionsPath: null, allowedPaths: ['${params.docsPath}', './src']${modelField(models.explorer)} },
-    builder:  { instructionsPath: null, writablePaths: ['./src', './tests']${modelField(models.builder)} },
-    reviewer: { instructionsPath: null${modelField(models.reviewer)} },
-    ${models.consultant ? `consultant: { instructionsPath: null${modelField(models.consultant)} },
-    ` : ""}custom:   [],
-  },
+function configTs(params) {
+  return `import type { HarnessConfig } from '@cardor/agent-harness-kit'
 
-  // SQLite (default). Switch to postgres/mysql by changing database.type.
-  // database: { type: 'postgres', connectionString: process.env.DATABASE_URL },
-  // database: { type: 'mysql',    connectionString: process.env.DATABASE_URL },
-  database: { type: 'sqlite', path: '.harness/harness.db' },
+const config: HarnessConfig = {
+${configObjectBody(params)}}
 
-  storage: {
-    dir:    '.harness',
-    tasks:  { adapter: '${params.tasksAdapter}' },
-    sections: {
-      toolsUsed:     true,
-      filesModified: true,
-      result:        true,
-      blockers:      true,
-      nextSteps:     false,
-    },
-    markdownFallback: { enabled: true, path: '.harness/current.md' },
-    // 'local' \u2014 DB lives in .harness/ (project-relative). 'global' \u2014 DB lives
-    // under ~/.harness/dbs/<projectId>/, outside the project tree.
-    scope:     '${params.scope}',
-    projectId: '${params.projectId}',
-  },
+export default config
+`;
+}
+function configMjs(params) {
+  return `const config = {
+${configObjectBody(params)}}
 
-  health: {
-    scriptPath: './health.sh',
-    required:   true,
-  },
+export default config
+`;
+}
+function configCjs(params) {
+  return `const config = {
+${configObjectBody(params)}}
 
-  tools: {
-    mcp:     { enabled: true, port: ${params.port} },
-    scripts: { enabled: true, outputDir: './.harness/scripts' },
-  },
-})
+module.exports = config
 `;
 }
 function agentLead(vars) {
@@ -789,14 +751,6 @@ function writeSkills(cwd2, skillsDir) {
     writeFileSync3(dest, readFileSync4(src, "utf8"), "utf8");
   }
 }
-function writeSkill(skillsRoot, skillName) {
-  const src = join4(__dirname2, "skills", skillName, "SKILL.md");
-  const destDir = join4(skillsRoot, skillName);
-  const dest = join4(destDir, "SKILL.md");
-  if (existsSync3(dest)) return;
-  mkdirSync3(destDir, { recursive: true });
-  writeFileSync3(dest, readFileSync4(src, "utf8"), "utf8");
-}
 
 // src/core/materializer/claude-code.ts
 var ClaudeCodeMaterializer = class {
@@ -1340,7 +1294,6 @@ import pc3 from "picocolors";
 
 // src/core/doctor.ts
 import { existsSync as existsSync9, readFileSync as readFileSync7 } from "fs";
-import { homedir } from "os";
 import { dirname as dirname6, join as join11 } from "path";
 import { fileURLToPath as fileURLToPath5 } from "url";
 
@@ -1503,55 +1456,6 @@ function checkSkills(cwd2, provider) {
   const skillsDir = getProviderSkillsDir(provider);
   return checkSkillsAtRoot(join11(cwd2, skillsDir));
 }
-function getGlobalProviderAgentDir(provider, homeDir) {
-  switch (provider) {
-    case "claude-code":
-      return { agentsDir: join11(homeDir, ".claude", "agents"), ext: ".md" };
-    case "opencode":
-      return { agentsDir: join11(homeDir, ".config", "opencode", "agents"), ext: ".md" };
-    case "codex-cli":
-      return { agentsDir: join11(homeDir, ".codex", "agents"), ext: ".toml" };
-    default:
-      return { agentsDir: join11(homeDir, ".claude", "agents"), ext: ".md" };
-  }
-}
-function getGlobalProviderSkillsDir(provider, homeDir) {
-  switch (provider) {
-    case "claude-code":
-      return join11(homeDir, ".claude", "skills");
-    case "opencode":
-      return join11(homeDir, ".config", "opencode", "skills");
-    case "codex-cli":
-      return join11(homeDir, ".agents", "skills");
-    default:
-      return join11(homeDir, ".claude", "skills");
-  }
-}
-async function getGlobalDoctorStatus(provider, config, homeDir = homedir()) {
-  const projectName = config.project.name;
-  const allowedPaths = (config.agents.explorer.allowedPaths ?? []).join(", ");
-  const writablePaths = (config.agents.builder.writablePaths ?? []).join(", ");
-  const models = {
-    lead: config.agents.lead.model,
-    explorer: config.agents.explorer.model,
-    consultant: config.agents.consultant?.model,
-    builder: config.agents.builder.model,
-    reviewer: config.agents.reviewer.model
-  };
-  const { agentsDir, ext } = getGlobalProviderAgentDir(provider, homeDir);
-  const agents = checkAgentFilesAtRoot(
-    agentsDir,
-    ext,
-    provider,
-    projectName,
-    allowedPaths,
-    writablePaths,
-    models
-  );
-  const skillsDir = getGlobalProviderSkillsDir(provider, homeDir);
-  const skills = checkSkillsAtRoot(skillsDir);
-  return { agents, skills };
-}
 async function getDoctorStatus(cwd2) {
   const lib = await checkLibVersion();
   let config;
@@ -1793,51 +1697,6 @@ import { join as join14 } from "path";
 import * as p3 from "@clack/prompts";
 import pc7 from "picocolors";
 
-// src/core/materializer/global-sync.ts
-import { homedir as homedir2 } from "os";
-async function syncGlobalAgentsAndSkills(config, provider, homeDir = homedir2()) {
-  const status = await getGlobalDoctorStatus(provider, config, homeDir);
-  const missingAgents = status.agents.filter((a) => a.status === "missing");
-  const missingSkills = status.skills.filter((s) => s.status === "missing");
-  if (missingAgents.length === 0 && missingSkills.length === 0) {
-    return { alreadySynced: true, createdAgents: [], createdSkills: [] };
-  }
-  const projectName = config.project.name;
-  const allowedPaths = (config.agents.explorer.allowedPaths ?? []).join(", ");
-  const writablePaths = (config.agents.builder.writablePaths ?? []).join(", ");
-  const models = {
-    lead: config.agents.lead.model,
-    explorer: config.agents.explorer.model,
-    consultant: config.agents.consultant?.model,
-    builder: config.agents.builder.model,
-    reviewer: config.agents.reviewer.model
-  };
-  const createdAgents = [];
-  if (missingAgents.length > 0) {
-    const { agentsDir, ext } = getGlobalProviderAgentDir(provider, homeDir);
-    for (const agent of missingAgents) {
-      const name = agent.name;
-      const content = generateExpectedAgentContent(name, provider, {
-        projectName,
-        allowedPaths,
-        writablePaths,
-        model: models[name]
-      });
-      writeAgentFile(agentsDir, `${name}${ext}`, content);
-      createdAgents.push(name);
-    }
-  }
-  const createdSkills = [];
-  if (missingSkills.length > 0) {
-    const skillsDir = getGlobalProviderSkillsDir(provider, homeDir);
-    for (const skill of missingSkills) {
-      writeSkill(skillsDir, skill.name);
-      createdSkills.push(skill.name);
-    }
-  }
-  return { alreadySynced: false, createdAgents, createdSkills };
-}
-
 // src/schema/init.ts
 import * as v from "valibot";
 var initNameSchema = v.pipe(
@@ -2079,7 +1938,7 @@ async function runInit(cwd2, flags) {
   const modelOverrides = {};
   if (provider === "claude-code" || provider === "codex-cli") {
     const wantsModelCustomization = await p3.confirm({
-      message: "\xBFPersonalizar el modelo por agente?",
+      message: "Customize the model per agent?",
       initialValue: false
     });
     if (p3.isCancel(wantsModelCustomization)) {
@@ -2090,7 +1949,7 @@ async function runInit(cwd2, flags) {
       if (provider === "claude-code") {
         for (const agent of AGENT_LABELS) {
           const val = await p3.select({
-            message: `Modelo para ${agent.label}`,
+            message: `Model for ${agent.label}`,
             options: [
               { value: "inherit", label: "inherit (default)" },
               { value: "haiku", label: "haiku" },
@@ -2109,8 +1968,8 @@ async function runInit(cwd2, flags) {
       } else {
         for (const agent of AGENT_LABELS) {
           const val = await p3.text({
-            message: `Modelo para ${agent.label} (Codex no valida este valor)`,
-            placeholder: "ej. gpt-5 (vac\xEDo o <3 caracteres = sin override)"
+            message: `Model for ${agent.label} (Codex does not validate this value)`,
+            placeholder: "e.g. gpt-5 (empty or <3 chars = no override)"
           });
           if (p3.isCancel(val)) {
             p3.cancel("Cancelled.");
@@ -2148,7 +2007,10 @@ async function runInit(cwd2, flags) {
       message: "Storage scope",
       options: [
         { value: "local", label: "Local \u2014 .harness/harness.db lives in this project" },
-        { value: "global", label: "Global \u2014 DB lives under ~/.harness/dbs/<projectId>/, outside the project" }
+        {
+          value: "global",
+          label: "Global \u2014 DB lives under ~/.harness/dbs/<projectId>/, outside the project"
+        }
       ],
       initialValue: "local"
     });
@@ -2212,7 +2074,6 @@ async function runInit(cwd2, flags) {
     firstTask = { title: taskTitle, description: taskDesc, acceptance };
   }
   let configExt = "ts";
-  let globalSyncResult = null;
   const spinner6 = p3.spinner();
   spinner6.start("Scaffolding...");
   try {
@@ -2246,9 +2107,6 @@ async function runInit(cwd2, flags) {
     const db = await openDB(config, installDir);
     await db.writeStorageState(installDir);
     await materializer.scaffold(config, { cwd: installDir, firstTask });
-    if (config.storage.scope === "global") {
-      globalSyncResult = await syncGlobalAgentsAndSkills(config, provider);
-    }
     if (firstTask) {
       const slug = slugify(firstTask.title);
       await db.addTask({
@@ -2272,8 +2130,16 @@ async function runInit(cwd2, flags) {
   console.log(pc7.green(`\u2713 agent-harness-kit.config.${configExt}`));
   console.log(pc7.green("\u2713 AGENTS.md"));
   console.log(pc7.green("\u2713 health.sh"));
-  console.log(pc7.green(storageScope === "global" ? "\u2713 ~/.harness/dbs/<projectId>/harness.db" : "\u2713 .harness/harness.db"));
-  console.log(pc7.green(storageScope === "global" ? "\u2713 ~/.harness/dbs/<projectId>/current.md" : "\u2713 .harness/current.md"));
+  console.log(
+    pc7.green(
+      storageScope === "global" ? "\u2713 ~/.harness/dbs/<projectId>/harness.db" : "\u2713 .harness/harness.db"
+    )
+  );
+  console.log(
+    pc7.green(
+      storageScope === "global" ? "\u2713 ~/.harness/dbs/<projectId>/current.md" : "\u2713 .harness/current.md"
+    )
+  );
   console.log(pc7.green("\u2713 .harness/storage-state.json"));
   console.log(pc7.green(`\u2713 ${agentsDir}lead.md`));
   console.log(pc7.green(`\u2713 ${agentsDir}explorer.md`));
@@ -2281,19 +2147,6 @@ async function runInit(cwd2, flags) {
   console.log(pc7.green(`\u2713 ${agentsDir}reviewer.md`));
   console.log(pc7.green(`\u2713 ${mcpFile}`));
   console.log(pc7.green("\u2713 .gitignore entries added"));
-  if (globalSyncResult) {
-    console.log("");
-    if (globalSyncResult.alreadySynced) {
-      console.log(pc7.dim("\u2713 Global agents/skills already synced \u2014 skipped"));
-    } else {
-      for (const name2 of globalSyncResult.createdAgents) {
-        console.log(pc7.green(`\u2713 ~global agent added: ${name2}`));
-      }
-      for (const name2 of globalSyncResult.createdSkills) {
-        console.log(pc7.green(`\u2713 ~global skill added: ${name2}`));
-      }
-    }
-  }
   console.log("");
   console.log(pc7.cyan("\u2192") + ` Edit ${pc7.cyan("health.sh")} with your project checks`);
   console.log(pc7.cyan("\u2192") + ` ${pc7.cyan("ahk task add")} to queue work for agents`);
@@ -2352,7 +2205,7 @@ async function runMigrate(cwd2, opts) {
 
 // src/commands/migrate-storage.ts
 import { copyFileSync, existsSync as existsSync12, mkdirSync as mkdirSync8, rmSync, writeFileSync as writeFileSync9 } from "fs";
-import { homedir as homedir3 } from "os";
+import { homedir } from "os";
 import { dirname as dirname7, join as join15, resolve as resolve8 } from "path";
 import pc9 from "picocolors";
 function log5(msg) {
@@ -2389,7 +2242,7 @@ function copySqliteFile(srcPath, destPath) {
     throw new Error(`Copy verification failed: ${destPath} does not exist after copy.`);
   }
 }
-async function runMigrateStorage(cwd2, opts, homeDir = homedir3()) {
+async function runMigrateStorage(cwd2, opts, homeDir = homedir()) {
   const config = await loadConfig(cwd2);
   const storageDir = config.storage.dir;
   const state = readStorageStateFile(cwd2, storageDir);
@@ -3750,7 +3603,10 @@ function isLocalInstallSatisfied(cwd2) {
   return false;
 }
 function printLocalInstallWarning() {
-  console.error(pc17.red(`\u2717 ${pkg.name} must be installed locally in this project.`));
+  console.error(pc17.yellow(`\u26A0 ${pkg.name} is not installed locally in this project.`));
+  console.error(pc17.dim("  This is only a recommendation for reproducibility: pinning a local"));
+  console.error(pc17.dim("  version keeps behavior consistent across your team and CI, instead of"));
+  console.error(pc17.dim("  drifting with whatever version is installed globally on each machine."));
   console.error(pc17.dim(`  Run: npm install --save-dev ${pkg.name}`));
   console.error(pc17.dim("  (or the equivalent for your package manager: pnpm add -D, yarn add --dev, bun add -d)"));
 }
@@ -3853,7 +3709,6 @@ program.command("doctor").description("Check lib version, agent files, and harne
 program.hook("preAction", () => {
   if (!isLocalInstallSatisfied(cwd)) {
     printLocalInstallWarning();
-    process.exit(1);
   }
 });
 program.hook("postAction", async () => {