@angelmsger/fx 0.0.0-stage → 0.10.1

package/README.md

@@ -1,3 +1,181 @@
-# Temporary Holding Version
+# fx-devkit
 
-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.
+**One manifest for your repositories, tools, and coding agents.**
+
+[![Node.js: 22 or newer](https://img.shields.io/badge/Node.js-%E2%89%A522-c4f36b?style=flat-square&labelColor=101211)](#requirements)
+[![License: Apache 2.0](https://img.shields.io/badge/license-Apache_2.0-c4f36b?style=flat-square&labelColor=101211)](LICENSE)
+
+[Documentation](docs/README.md) · [Quick start](#quick-start) ·
+[Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md)
+
+English · [日本語](docs/website/i18n/ja/getting-started.md) ·
+[简体中文](docs/website/i18n/zh-Hans/getting-started.md) ·
+[繁體中文](docs/website/i18n/zh-Hant/getting-started.md)
+
+`fx` prepares a multi-repository workspace from your team's versioned manifest.
+It synchronizes checkouts, prepares companion tools and agent resources, and
+locates services, owners and environment-specific diagnostics. Each repository
+keeps its own history, branches, dependencies and build system.
+
+- Preview writes with `--dry-run`; sync preserves dirty and diverged checkouts.
+- Share repository, tool and environment definitions while keeping personal
+  selections and credentials local.
+- Use human output interactively or JSON with explicit status and recovery steps.
+- Keep authentication and service APIs in the companion tools you already use.
+
+## Requirements
+
+Use Node.js 22 or newer, Git and npm. Bun is also supported as an alternative
+runtime. macOS and Linux are supported; native Windows execution and agent host
+activation remain unverified. See [platform support](docs/support.md#platform-support).
+
+The documentation follows current source. See the [version history](CHANGELOG.md)
+for release changes; an installed package's help and bundled Skill describe
+that executable.
+
+You also need a team manifest. Use an existing source or
+[create one from your checkouts](docs/manifest-guide.md).
+
+## Install
+
+The internal package is `@fx/devkit`; the public package is `@angelmsger/fx` on
+npmjs. Both provide `fx`.
+
+<!-- distribution:internal -->
+
+For the internal package, use your team's existing npm configuration. If its
+`@fx` scope is not configured yet, sign in once with the team Registry URL.
+The URL below is fictional:
+
+```sh
+npm login --registry=https://npm.example.com/ --scope=@fx
+npm install -g @fx/devkit
+fx --version
+```
+
+<!-- /distribution -->
+
+<!-- distribution:public -->
+
+Install from npmjs:
+
+```sh
+npm install -g @angelmsger/fx --registry=https://registry.npmjs.org/ --@angelmsger:registry=https://registry.npmjs.org/
+fx --version
+```
+
+<!-- /distribution -->
+
+See the [installation guide](docs/user-guide.md#install) for source installations,
+PowerShell commands and Registry routing. For updates, use
+[Support and updates](docs/support.md#updates).
+
+## Quick start
+
+You need two things: the manifest source supplied by your team and a directory
+for the workspace. You can ask your coding agent: “Use fx to prepare this manifest
+in this directory.” If you are running the commands yourself:
+
+```sh
+fx init ./work --from <manifest-repository> --dry-run
+fx init ./work --from <manifest-repository>
+```
+
+fx checks the source, prepares authorized local tools and configuration, clones
+the selected repositories, and prepares the Agent guides and Skills. The name
+is derived from the directory and avoids existing registrations. Existing files
+and completed work are preserved.
+Review the displayed commands before approving new manifest actions.
+
+When fx reports **Ready to work**, you can start. If it needs personal sign-in,
+access or approval, it reports the remaining items together. Complete those
+items and use the printed continuation command:
+
+```sh
+fx init --resume --workspace work
+```
+
+A continuation verifies current state and skips completed preparation. It does
+not reimport a directory source or rebuild checkouts. You do not need to choose
+internal stages or run a separate diagnostic sequence to finish initialization.
+
+New workspaces select all shared repositories. To limit the first download,
+[choose repositories](docs/user-guide.md#choose-repositories-before-downloading) and add `--repos`
+to the initial preview and apply. Existing directories are adopted automatically.
+For everyday updates use `fx sync`; `fx status` shows repository state. To work on a repository not downloaded yet, ask your Agent or follow `fx repo show <name>` and its `next_steps`.
+
+## Everyday commands
+
+| Task                           | Command                                               |
+| ------------------------------ | ----------------------------------------------------- |
+| Find managed workspaces        | `fx workspace list` / `fx workspace show <name>`      |
+| Inspect checkouts              | `fx status`                                           |
+| Preview updates                | `fx sync --dry-run`                                   |
+| Replace a repository selection | `fx repo select <name...>` / `fx repo select --all`   |
+| Select repositories            | `fx repo pick <name...>` / `fx repo unpick <name...>` |
+| Select environments            | `fx env pick <name...>` / `fx env unpick <name...>`   |
+| Find a service                 | `fx where <repo> --env <environment>`                 |
+| List capabilities              | `fx can`                                              |
+| Check a capability             | `fx can <capability> --env <environment>`             |
+| Refresh guides and Skills      | `fx sync --only docs,skills`                          |
+| Inspect release checks         | `fx release --format json`                            |
+
+Use `repo list`, `env list`, `agent list` and `tool list` to discover valid names.
+Use `repo select` and `env select` to choose an exact set, `--all` to follow the
+team's full set including future additions, or `--none` to select nothing.
+`pick/unpick` add or remove individual names. First-time setup can limit cloning
+with `fx init ./work --from <manifest-repository> --repos example-api,example-web --dry-run`.
+`where` prints coordinates and commands; it does not execute those commands.
+`release` reports on your repositories; it does not publish packages or deploy them.
+The [CLI reference](docs/cli/README.md) and `fx <command> --help` own exact syntax.
+
+## For coding agents
+
+Run `fx self info --format json`, then read `SKILL.md` in its `bundled_skill`
+directory, or run `fx skill show`. No Skill-loaded environment declaration is
+required. Global Skill installation is optional. Start sessions at the registered workspace root to use team guidance.
+
+Document updates recheck their planning snapshots and return `DOCS_WRITE_CONFLICT`
+when they detect an intervening change. Partial docs results distinguish completed and
+pending writes; inspect them before retrying.
+
+`login` preserves partial results on stdout when it needs human input or a later
+step fails. Read those results alongside stderr errors before retrying; the
+[user guide](docs/user-guide.md) describes the result and recovery fields.
+
+`init`, `sync`, `doctor` and `release` summarize JSON by default. Use `--details`
+for full results or `--fields` to select fields from those results in any output
+format. Explicit projection emits one report object in JSON/NDJSON and selected
+key/value pairs in human output. Keep stdout
+separate from diagnostic stderr. Do not repeat a write just to obtain a different
+view of its output.
+
+For `init`, `sync` and `doctor`, read `preparation.state` and the scoped blockers.
+Incomplete preparation exits 12; continuation is `fx init --resume --workspace <name>`.
+Release checks retain their separate `ok` and `complete` fields.
+
+## Configuration
+
+`fx config list` shows settings and their sources. `fx config get <key> --explain`
+shows the effective value. Explicit flags override environment, file and defaults.
+
+Agent selection applies across workspaces in the same `FX_HOME`:
+`fx config set agents codex` selects Codex; `fx config set agents ''` selects none.
+`fx config unset agents` restores detection when `FX_AGENTS` is also unset.
+`FX_HOME` relocates fx state, but not global Skills or companion credentials.
+
+For service presets, tool installation history, host resources and shell
+completion, see the [user guide](docs/user-guide.md). For information sharing and
+local data, see [Your data and credentials](docs/user-privacy.md).
+
+## Contributing and support
+
+[CONTRIBUTING.md](CONTRIBUTING.md) covers local setup, checks and pull requests.
+[Architecture](docs/design/README.md) describes current contracts;
+[Roadmap](docs/roadmap.md) lists possible extensions.
+
+Report reproducible problems through [support](docs/support.md#report-an-issue).
+Include the version, operating system, command and a redacted reproduction.
+Report vulnerabilities privately using [SECURITY.md](SECURITY.md).
+
+Licensed under the [Apache License, Version 2.0](LICENSE).

package/bin/fx.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+// The only file that knows where the compiled entry lives.
+const argv = process.argv.slice(2);
+if (
+  (argv[0] === 'hook' && argv[1] === 'dispatch' && !argv.includes('--help')) ||
+  argv[0] === '__hook-background'
+) {
+  import('../dist/cli/hook-entry.js')
+    .then((m) =>
+      m.hookMain(argv.slice(argv[0] === 'hook' ? 2 : 1), argv[0] === '__hook-background'),
+    )
+    .catch(() => {
+      process.exitCode = 0;
+    });
+} else {
+  import('../dist/cli/main.js').then((m) => m.main(argv));
+}

package/bin/mcp-stdio.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// No CLI initialization may write to this protocol's stdout.
+import('../dist/cli/mcp-stdio.js')
+  .then((entry) => entry.mcpStdioMain(process.argv.slice(2)))
+  .catch(() => {
+    process.exitCode = 1;
+  });

package/defaults/tools.yaml

@@ -0,0 +1,90 @@
+# The catalog of companion CLIs fx knows how to drive: version floor, install
+# method and commands, and nothing team-specific. A team's manifest/tools.yaml
+# is a patch over it: entries match by name, objects merge, a null deletes a
+# field, `enabled: false` retires a tool.
+#
+# Nothing here is a requirement. A workspace's toolchain is read off its
+# provider bindings — binding `ci` to jenkins-cli is what puts jenkins-cli in
+# the toolchain — together with whatever its patch names outright. Everything
+# else stays in the catalog, unselected. The commands below are fx's own, so
+# no one confirms them by hand; a field a patch overrides becomes the team's
+# and is confirmed again.
+schema_version: 3
+defaults:
+  version_args: [--version]
+  install: [{ via: npm }]
+  skill: { command: [skill, install], dir_flag: --dir }
+  auth: { command: [auth, status] }
+tools:
+  - name: bitbucket-cli
+    desc: Repositories, forks, pull requests and code review on Bitbucket
+    min_version: '0.24.0'
+    install: [{ via: npm, spec: '@angelmsger/bitbucket-cli' }]
+    docs: https://github.com/AngelMsger/bitbucket-cli
+  - name: confluence-cli
+    min_version: '0.21.0'
+    desc: Pages, spaces and comments in Confluence
+    install: [{ via: npm, spec: '@angelmsger/confluence-cli' }]
+    docs: https://github.com/AngelMsger/confluence-cli
+  - name: jenkins-cli
+    min_version: '0.10.0'
+    desc: Jobs, builds and console output in Jenkins
+    install: [{ via: npm, spec: '@angelmsger/jenkins-cli' }]
+    docs: https://github.com/AngelMsger/jenkins-cli
+  - name: openobserve-cli
+    min_version: '0.14.0'
+    desc: Logs, metrics and traces in OpenObserve
+    install: [{ via: npm, spec: '@angelmsger/openobserve-cli' }]
+    docs: https://github.com/AngelMsger/openobserve-cli
+  - name: prometheus-cli
+    min_version: '0.2.0'
+    desc: PromQL queries, series discovery, scrape targets and alerts in Prometheus
+    install: [{ via: npm, spec: '@angelmsger/prometheus-cli' }]
+    docs: https://github.com/AngelMsger/prometheus-cli
+  - name: jira-cli
+    min_version: '0.7.0'
+    desc: Issues, comments, transitions and worklogs in Jira
+    install: [{ via: npm, spec: '@angelmsger/jira-cli' }]
+    docs: https://github.com/AngelMsger/jira-cli
+  - name: sentry
+    min_version: '0.44.1'
+    desc: Issues, events and releases in Sentry
+    install: [{ via: npm, spec: sentry }]
+    skill: { command: [] }
+    auth: { command: [auth, status] }
+    docs: https://cli.sentry.dev/getting-started/installation/
+  - name: kubectl
+    min_version: '1.37.0'
+    desc: Read-only access to Kubernetes clusters
+    version_args: [version, --client]
+    install:
+      - { via: brew, spec: kubectl }
+      - { via: manual }
+    skill: { command: [] }
+    auth: { command: [] }
+    docs: https://kubernetes.io/docs/reference/kubectl/
+  - name: lark-cli
+    min_version: '1.0.94'
+    desc: Feishu / Lark messaging, documents, calendar and more
+    install: [{ via: npm, spec: '@larksuite/cli' }]
+    skill: { command: [] }
+    auth: { command: [auth, status] }
+  - name: meegle
+    min_version: '1.0.23'
+    desc: Feishu Project (Meegle) work items
+    install: [{ via: npm, spec: '@lark-project/meegle' }]
+    skill: { command: [] }
+    auth: { command: [] }
+  - name: wecom-cli
+    min_version: '1.2.1'
+    desc: WeCom messaging, documents and calendar
+    install: [{ via: npm, spec: '@wecom/cli' }]
+    skill: { command: [] }
+    auth: { command: [] }
+  - name: tmeet
+    min_version: '1.0.18'
+    desc: Tencent Meeting meetings, recordings, minutes and transcripts
+    install: [{ via: npm, spec: '@tencentcloud/tmeet' }]
+    skill: { command: [] }
+    auth: { command: [] }
+    docs: https://github.com/TencentCloud/tencentmeeting-cli

package/dist/adapters/agent-host/extension-hooks.js

@@ -0,0 +1,123 @@
+// Project extensions bridge a native lifecycle event to the same fx process
+// entry. A content digest protects a bridge somebody edited after projection.
+import { createHash } from 'node:crypto';
+export class ExtensionHookProtocol {
+    project(input) {
+        if (input.current !== null && !isOwned(input.current, input.owner))
+            return { text: input.current, status: 'foreign' };
+        if (input.remove)
+            return { text: null, status: 'managed' };
+        const body = renderBridge(input);
+        return { text: `${body}// fx:content ${digest(body)}\n`, status: 'managed' };
+    }
+    context(text, _support) {
+        return text ? JSON.stringify({ context: text }) : '';
+    }
+    decode(text, _support) {
+        try {
+            const input = JSON.parse(text);
+            if (typeof input !== 'object' ||
+                input === null ||
+                !('cwd' in input) ||
+                typeof input.cwd !== 'string')
+                return null;
+            return { cwd: input.cwd, sessionId: null };
+        }
+        catch {
+            return null;
+        }
+    }
+}
+function digest(text) {
+    return createHash('sha256').update(text).digest('hex');
+}
+function isOwned(text, owner) {
+    const at = text.lastIndexOf('// fx:content ');
+    return (text.startsWith(`// fx:derived ${owner}\n`) &&
+        at >= 0 &&
+        text.slice(at).trim() === `// fx:content ${digest(text.slice(0, at))}`);
+}
+function renderBridge(input) {
+    return `// fx:derived ${input.owner}
+import { spawn, spawnSync, type ChildProcess } from 'node:child_process';
+import path from 'node:path';
+const vector: string[] = ${JSON.stringify([...input.vector, '--owner', input.owner])};
+const event = ${JSON.stringify(input.event)};
+${BRIDGE_PROGRAM}`;
+}
+const BRIDGE_PROGRAM = `interface Host {
+  on(event: string, handler: (event: unknown, context: { cwd: string }) => Promise<void>): void;
+  sendMessage(message: { customType: string; content: string; display: boolean }, options: { triggerTurn: boolean }): void;
+}
+export default function register(host: Host): void {
+  const pending = new Set<() => void>();
+  host.on('session_shutdown', async () => {
+    for (const cancel of [...pending]) cancel();
+  });
+  host.on(event, async (_event, context) => {
+    try { await run(host, context.cwd, pending); }
+    catch { /* A lifecycle failure must not fail the host session. */ }
+  });
+}
+function run(host: Host, cwd: string, pending: Set<() => void>): Promise<void> {
+  return new Promise<void>((resolve) => {
+    const child = spawn(vector[0]!, vector.slice(1), {
+      cwd, stdio: ['pipe', 'pipe', 'ignore'], detached: process.platform !== 'win32', windowsHide: true,
+    });
+    let output = '';
+    let done = false;
+    let force: ReturnType<typeof setTimeout> | undefined;
+    const finish = (): void => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      pending.delete(cancel);
+      resolve();
+    };
+    const cancel = (): void => {
+      if (done) return;
+      output = '';
+      signal(child, 'SIGTERM');
+      force = setTimeout(() => signal(child, 'SIGKILL'), 250);
+      finish();
+    };
+    const timer = setTimeout(cancel, 3000);
+    pending.add(cancel);
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', chunk => {
+      if (done) return;
+      output += chunk.toString();
+      if (Buffer.byteLength(output) > 8192) cancel();
+    });
+    child.on('error', finish);
+    child.on('close', code => {
+      clearTimeout(force);
+      if (!done && code === 0) deliver(host, output);
+      finish();
+    });
+    child.stdin.on('error', () => {});
+    child.stdin.end(JSON.stringify({ cwd }));
+  });
+}
+function signal(child: ChildProcess, name: 'SIGTERM' | 'SIGKILL'): void {
+  try {
+    if (process.platform !== 'win32' && child.pid !== undefined) process.kill(-child.pid, name);
+    else {
+      if (child.pid !== undefined && child.exitCode === null && child.signalCode === null) {
+        const executable = path.join(process.env.SystemRoot ?? 'C:\\\\Windows', 'System32', 'taskkill.exe');
+        const result = spawnSync(executable, ['/PID', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true, timeout: 500 });
+        if (result.status === 0) return;
+      }
+      child.kill(name);
+    }
+  } catch { child.kill(name); }
+}
+function deliver(host: Host, output: string): void {
+  try {
+    const result: unknown = JSON.parse(output);
+    if (typeof result === 'object' && result !== null && 'context' in result && typeof result.context === 'string')
+      host.sendMessage({ customType: 'fx-workspace', content: result.context, display: false }, { triggerTurn: false });
+  } catch { /* Invalid or late context is discarded. */ }
+}
+`;
+//# sourceMappingURL=extension-hooks.js.map

package/dist/adapters/agent-host/extension-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension-hooks.js","sourceRoot":"","sources":["../../../src/adapters/agent-host/extension-hooks.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,8EAA8E;AAE9E,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AASzC,MAAM,OAAO,qBAAqB;IAChC,OAAO,CAAC,KAA0B;QAChC,IAAI,KAAK,CAAC,OAAO,KAAK,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC;YAChE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;QACpD,IAAI,KAAK,CAAC,MAAM;YAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;QAC3D,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;QACjC,OAAO,EAAE,IAAI,EAAE,GAAG,IAAI,iBAAiB,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAC/E,CAAC;IAED,OAAO,CAAC,IAAY,EAAE,QAAqB;QACzC,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACvD,CAAC;IAED,MAAM,CAAC,IAAY,EAAE,QAAqB;QACxC,IAAI,CAAC;YACH,MAAM,KAAK,GAAY,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACxC,IACE,OAAO,KAAK,KAAK,QAAQ;gBACzB,KAAK,KAAK,IAAI;gBACd,CAAC,CAAC,KAAK,IAAI,KAAK,CAAC;gBACjB,OAAO,KAAK,CAAC,GAAG,KAAK,QAAQ;gBAE7B,OAAO,IAAI,CAAC;YACd,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QAC7C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;CACF;AAED,SAAS,MAAM,CAAC,IAAY;IAC1B,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACzD,CAAC;AAED,SAAS,OAAO,CAAC,IAAY,EAAE,KAAa;IAC1C,MAAM,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,gBAAgB,CAAC,CAAC;IAC9C,OAAO,CACL,IAAI,CAAC,UAAU,CAAC,iBAAiB,KAAK,IAAI,CAAC;QAC3C,EAAE,IAAI,CAAC;QACP,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,iBAAiB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CACvE,CAAC;AACJ,CAAC;AAED,SAAS,YAAY,CAAC,KAA0B;IAC9C,OAAO,iBAAiB,KAAK,CAAC,KAAK;;;2BAGV,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;gBACpE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC;EACzC,cAAc,EAAE,CAAC;AACnB,CAAC;AAED,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0EtB,CAAC"}

package/dist/adapters/agent-host/host.js

@@ -0,0 +1,62 @@
+// One AgentHost for any agent in the spec table, so the whole family is this
+// class plus data. Presence is a marker under the home directory or the
+// agent's own binary on PATH; a project Skill directory is resolved against
+// the root it is asked about, never against cwd.
+import path from 'node:path';
+export class SpecAgentHost {
+    spec;
+    deps;
+    constructor(spec, deps) {
+        this.spec = spec;
+        this.deps = deps;
+    }
+    get id() {
+        return this.spec.id;
+    }
+    get label() {
+        return this.spec.label;
+    }
+    get hooks() {
+        return this.spec.hooks ?? null;
+    }
+    get mcp() {
+        return (this.spec.mcp ?? {
+            status: 'unverified',
+            reason: 'No verified project MCP protocol is registered for this host.',
+        });
+    }
+    get rules() {
+        return this.spec.rules ?? null;
+    }
+    async detect(scope = 'global', projectRoot = '.') {
+        const base = scope === 'project' ? projectRoot : this.deps.home;
+        const markers = scope === 'project' ? this.spec.projectMarkers : this.spec.markers;
+        for (const marker of markers) {
+            if (await this.deps.fs.exists(path.join(base, marker)))
+                return true;
+        }
+        if (scope === 'project')
+            return false;
+        for (const binary of this.spec.binaries) {
+            if ((await this.deps.process.which(binary)) !== undefined)
+                return true;
+        }
+        return false;
+    }
+    skillsDir(scope, projectRoot) {
+        return scope === 'global'
+            ? path.join(this.deps.home, this.spec.homeSub, 'skills')
+            : path.join(projectRoot ?? '.', this.spec.projectSkills);
+    }
+    projectPaths() {
+        const { hooks, mcp, rules } = this.spec;
+        return [
+            this.spec.projectSkills,
+            ...this.spec.projectMarkers,
+            ...(hooks === undefined ? [] : [hooks.projectPath]),
+            ...(mcp?.status === 'supported' ? [mcp.projectPath] : []),
+            ...(rules === undefined ? [] : [rules.projectPath]),
+        ];
+    }
+}
+//# sourceMappingURL=host.js.map

package/dist/adapters/agent-host/host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.js","sourceRoot":"","sources":["../../../src/adapters/agent-host/host.ts"],"names":[],"mappings":"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"}

package/dist/adapters/agent-host/json-hooks.js

@@ -0,0 +1,163 @@
+// Native command-hook documents are edited at syntax offsets. Only marked
+// handlers and their separators change; unrelated values are never serialized.
+import { findNodeAtLocation, parseTree } from 'jsonc-parser';
+import { ownsWindowsHook, windowsHookCommand } from '../process/powershell.js';
+export class JsonHookProtocol {
+    windowsCommand;
+    constructor(windowsCommand) {
+        this.windowsCommand = windowsCommand;
+    }
+    decode(text, support) {
+        try {
+            const input = JSON.parse(text);
+            if (typeof input !== 'object' ||
+                input === null ||
+                !('cwd' in input) ||
+                typeof input.cwd !== 'string')
+                return null;
+            const session = input[support.sessionKey ?? 'session_id'];
+            return { cwd: input.cwd, sessionId: typeof session === 'string' ? session : null };
+        }
+        catch {
+            return null;
+        }
+    }
+    context(text, support, event = 'session-start') {
+        if (!text || support.context === 'none')
+            return '';
+        return JSON.stringify({
+            hookSpecificOutput: {
+                hookEventName: support.events[event],
+                additionalContext: text,
+            },
+        });
+    }
+    project(input) {
+        if (input.remove && input.current === null)
+            return { text: null, status: 'managed' };
+        const current = input.current ?? '{}';
+        const errors = [];
+        const tree = parseTree(current, errors, { disallowComments: true, allowTrailingComma: false });
+        if (!tree || tree.type !== 'object' || errors.length || hasDuplicates(tree))
+            return { text: input.current, status: 'invalid' };
+        const hooks = findNodeAtLocation(tree, ['hooks']);
+        const event = findNodeAtLocation(tree, ['hooks', input.event]);
+        if ((hooks && hooks.type !== 'object') || (event && event.type !== 'array'))
+            return { text: input.current, status: 'invalid' };
+        const handler = commandHandler(input, this.windowsCommand);
+        const edits = [];
+        const removals = new Map();
+        let retained = false;
+        for (const group of event?.children ?? []) {
+            const handlers = findNodeAtLocation(group, ['hooks']);
+            if (!handlers || handlers.type !== 'array')
+                return { text: input.current, status: 'invalid' };
+            const owned = (handlers.children ?? []).filter((node) => isOwned(node, input.owner));
+            if (!owned.length)
+                continue;
+            if (input.remove &&
+                owned.length === handlers.children?.length &&
+                group.children?.length === 1) {
+                removals.set(event, [...(removals.get(event) ?? []), group]);
+                continue;
+            }
+            for (const node of owned) {
+                if (input.remove || retained)
+                    removals.set(handlers, [...(removals.get(handlers) ?? []), node]);
+                else {
+                    retained = true;
+                    const next = JSON.stringify(handler);
+                    if (current.slice(node.offset, node.offset + node.length) !== next)
+                        edits.push({ start: node.offset, end: node.offset + node.length, text: next });
+                }
+            }
+        }
+        if (!input.remove && !retained)
+            edits.push(insertHandler(tree, hooks, event, input.event, handler));
+        for (const [parent, nodes] of removals)
+            edits.push(...removeNodes(parent, nodes));
+        const text = applyEdits(current, edits);
+        return { text, status: 'managed', empty: input.remove && isEmptyDocument(text) };
+    }
+}
+function renderCommand(vector) {
+    return vector.map((arg) => `'${arg.replaceAll("'", "'\\''")}'`).join(' ');
+}
+function isOwned(node, owner) {
+    const command = findNodeAtLocation(node, ['command'])?.value;
+    return (findNodeAtLocation(node, ['type'])?.value === 'command' &&
+        typeof command === 'string' &&
+        (ownsWindowsHook(command, owner) ||
+            command.endsWith(renderCommand(['--owner', owner])) ||
+            command.endsWith(`${renderCommand(['--owner', owner])} 2>/dev/null || :`)));
+}
+function commandHandler(input, windows) {
+    const vector = [...input.vector, '--owner', input.owner];
+    if (!windows)
+        return { type: 'command', command: `${renderCommand(vector)} 2>/dev/null || :`, timeout: 3 };
+    const command = windowsHookCommand(vector, input.owner);
+    return {
+        type: 'command',
+        command,
+        timeout: 3,
+        ...(windows === 'powershell' ? { shell: 'powershell' } : {}),
+        ...(windows === 'override' ? { commandWindows: command } : {}),
+    };
+}
+function insertHandler(root, hooks, event, name, handler) {
+    const group = { hooks: [handler] };
+    if (event)
+        return append(event, JSON.stringify(group));
+    if (hooks)
+        return append(hooks, `${JSON.stringify(name)}:${JSON.stringify([group])}`);
+    return append(root, `"hooks":${JSON.stringify({ [name]: [group] })}`);
+}
+function append(node, text) {
+    const last = node.children?.at(-1);
+    const at = last ? last.offset + last.length : node.offset + 1;
+    return { start: at, end: at, text: `${last ? ',' : ''}${text}` };
+}
+function removeNodes(parent, nodes) {
+    const siblings = parent.children ?? [];
+    const removed = new Set(nodes);
+    const edits = [];
+    for (let i = 0; i < siblings.length; i++) {
+        const first = siblings[i];
+        if (!removed.has(first))
+            continue;
+        const previous = siblings[i - 1];
+        while (i + 1 < siblings.length && removed.has(siblings[i + 1]))
+            i++;
+        const last = siblings[i];
+        const next = siblings[i + 1];
+        if (previous)
+            edits.push({
+                start: previous.offset + previous.length,
+                end: last.offset + last.length,
+                text: '',
+            });
+        else
+            edits.push({ start: first.offset, end: next?.offset ?? last.offset + last.length, text: '' });
+    }
+    return edits;
+}
+function applyEdits(text, edits) {
+    for (const edit of [...edits].sort((a, b) => b.start - a.start))
+        text = text.slice(0, edit.start) + edit.text + text.slice(edit.end);
+    return text;
+}
+function hasDuplicates(node) {
+    if (node.type === 'object') {
+        const names = (node.children ?? []).map((property) => property.children?.[0]?.value);
+        if (new Set(names).size !== names.length)
+            return true;
+    }
+    return (node.children ?? []).some(hasDuplicates);
+}
+function isEmptyDocument(text) {
+    const doc = JSON.parse(text);
+    if (Object.keys(doc).some((key) => key !== 'hooks'))
+        return false;
+    return Object.values((doc['hooks'] ?? {})).every((value) => Array.isArray(value) && value.length === 0);
+}
+//# sourceMappingURL=json-hooks.js.map