@asc-agent/runtime 0.3.1 → 0.4.0

package/dist/adapters/jam/mcp-client.js

@@ -10,6 +10,7 @@
 //   stderr를 프로토콜로 읽지 않는다 — 진단용으로만 쓰고, 그것도 길이를 제한한다
 //   자격 값을 절대 기록하지 않는다 — 이 파일은 토큰을 받지도, 보지도, 남기지도 않는다
 import { spawn } from 'node:child_process';
+import { resolveExternalCommand } from "../../core/distribution/external-command.js";
 const PROTOCOL_VERSION = '2024-11-05';
 /** 진단으로 남길 stderr 최대 길이. 무한히 모으면 그 자체가 새는 곳이 된다. */
 const STDERR_KEEP = 2000;
@@ -30,9 +31,12 @@ export class JamMcpClient {
         if (this.#ready && this.#child)
             return { ok: true, value: { name: '', version: '' } };
         try {
+            // Windows에서 `jam` 은 npm `.cmd` shim이다 — bare 이름 spawn은 ENOENT가 나고
+            // (asc init 실측: "spawn jam ENOENT"), 실행 형태를 해석해야 세 OS에서 같다.
+            const resolved = resolveExternalCommand(this.#deps.command, this.#deps.args ?? []);
             this.#child = this.#deps.spawnProcess
                 ? this.#deps.spawnProcess()
-                : spawn(this.#deps.command, [...(this.#deps.args ?? [])], {
+                : spawn(resolved.command, resolved.args, {
                     stdio: ['pipe', 'pipe', 'pipe'],
                     ...(this.#deps.cwd ? { cwd: this.#deps.cwd } : {}),
                 });

package/dist/adapters/jam/setup.d.ts

@@ -0,0 +1,62 @@
+/** JAM 의 zero-install 진입. **버전을 여기 박지 않는다** — JAM 이 말한 값을 쓴다. */
+export declare const JAM_BOOTSTRAP = "@jam-mcp/bootstrap";
+/**
+ * 정확한 버전으로 고정한 공식 명령.
+ *
+ * JAM 문서가 `@latest` 를 금지하고 정확한 핀을 요구한다. 그 버전을 ASC 가 정하면 두
+ * 제품의 릴리스가 묶이므로, **돌고 있는 JAM 이 스스로 말한 버전**(doctor 의
+ * `axes.packageVersion`)을 그대로 쓴다.
+ */
+export declare function jamBootstrapCommand(version: string, args: readonly string[]): {
+    command: string;
+    args: string[];
+};
+/** `setup plan --json` 에서 우리가 읽는 부분. */
+export type JamSetupPlan = {
+    status?: string;
+    /** 사람이 결정해야 하는 것이 남아 있는가. 남아 있으면 ASC 는 손대지 않는다. */
+    requiresUserAction?: boolean;
+    changes?: unknown[];
+    project?: {
+        key?: string;
+        keySource?: string;
+    };
+    code?: string;
+    error?: string;
+};
+export type JamHealOutcome = 
+/** 고칠 것이 없었다. */
+{
+    kind: 'ALREADY_READY';
+}
+/** ASC 가 JAM 공식 setup 으로 고쳤다. */
+ | {
+    kind: 'HEALED';
+    changes: number;
+}
+/** 사람이 해야 한다 — 자격, 또는 진짜 프로젝트 선택. */
+ | {
+    kind: 'NEEDS_HUMAN';
+    detail: string;
+}
+/** 다시 돌려도 달라지지 않는다. */
+ | {
+    kind: 'FAILED';
+    detail: string;
+};
+export type JamSetupDeps = {
+    cwd: string;
+    /** JAM 이 말한 자기 버전. 없으면 부를 수 없다 — 버전을 지어내지 않는다. */
+    version: string;
+    /** 프로세스 실행 통로. 테스트가 실제 npx 를 부르지 않기 위한 주입점. */
+    exec?: (command: string, args: readonly string[], cwd: string) => Promise<string>;
+};
+/**
+ * 준비되지 않은 JAM 을 공식 경로로 되살린다.
+ *
+ * **계획을 먼저 본다.** 계획이 사람을 요구하면 적용하지 않는다 — 그것이 자격이거나 진짜
+ * 프로젝트 선택이고, 둘 다 ASC 가 대신할 수 없는 것이다 (설계 §9.4).
+ */
+export declare function healJam(deps: JamSetupDeps): Promise<JamHealOutcome>;
+/** 사람이 읽는 한 줄. 무엇을 했는지·무엇이 남았는지가 여기 있어야 한다. */
+export declare function healLine(outcome: JamHealOutcome): string;

package/dist/adapters/jam/setup.js

@@ -0,0 +1,85 @@
+// JAM 준비 상태를 JAM 의 공식 경로로 되살린다 (설계 §9.2·§9.3).
+//
+// **진단도 수리도 JAM 이 한다.** ASC 가 하는 일은 셋뿐이다:
+//
+//   언제 부를지 정한다      Profile 이 work binding 을 선언했는데 JAM 이 준비되지 않았을 때
+//   무엇을 부를지 고른다     JAM 이 스스로 말한 버전의 공식 bootstrap
+//   어디서 멈출지 판단한다   사람만 할 수 있는 것은 사람에게 넘긴다
+//
+// ASC 는 Jira 토큰을 받지도 저장하지도 않고, 프로젝트 키를 만들어 내지도 않는다.
+// 키는 Profile 에 이미 사람이 적어 둔 것이고, 그 결정을 다시 묻지 않는다.
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const run = promisify(execFile);
+/** JAM 의 zero-install 진입. **버전을 여기 박지 않는다** — JAM 이 말한 값을 쓴다. */
+export const JAM_BOOTSTRAP = '@jam-mcp/bootstrap';
+/**
+ * 정확한 버전으로 고정한 공식 명령.
+ *
+ * JAM 문서가 `@latest` 를 금지하고 정확한 핀을 요구한다. 그 버전을 ASC 가 정하면 두
+ * 제품의 릴리스가 묶이므로, **돌고 있는 JAM 이 스스로 말한 버전**(doctor 의
+ * `axes.packageVersion`)을 그대로 쓴다.
+ */
+export function jamBootstrapCommand(version, args) {
+    return { command: 'npx', args: ['--yes', `${JAM_BOOTSTRAP}@${version}`, ...args] };
+}
+const defaultExec = async (command, args, cwd) => {
+    try {
+        const { stdout } = await run(command, [...args], { cwd, maxBuffer: 8 * 1024 * 1024 });
+        return stdout;
+    }
+    catch (error) {
+        // JAM 은 준비되지 않았을 때도 JSON 을 내면서 0 이 아닌 코드로 끝난다.
+        const stdout = error.stdout;
+        if (stdout)
+            return stdout;
+        throw error;
+    }
+};
+/**
+ * 준비되지 않은 JAM 을 공식 경로로 되살린다.
+ *
+ * **계획을 먼저 본다.** 계획이 사람을 요구하면 적용하지 않는다 — 그것이 자격이거나 진짜
+ * 프로젝트 선택이고, 둘 다 ASC 가 대신할 수 없는 것이다 (설계 §9.4).
+ */
+export async function healJam(deps) {
+    const exec = deps.exec ?? defaultExec;
+    const read = async (args) => {
+        const { command, args: full } = jamBootstrapCommand(deps.version, args);
+        try {
+            return JSON.parse(await exec(command, full, deps.cwd));
+        }
+        catch (error) {
+            return { error: String(error.message ?? error).slice(0, 300) };
+        }
+    };
+    const plan = await read(['setup', 'plan', '--json']);
+    if (plan.error)
+        return { kind: 'FAILED', detail: `JAM setup plan 을 읽지 못했다 — ${plan.error}` };
+    if (plan.requiresUserAction) {
+        // 사람만 할 수 있는 것이 남았다. 대신 하지 않고, 무엇인지 그대로 전한다.
+        return { kind: 'NEEDS_HUMAN', detail: plan.code ?? plan.status ?? 'JAM setup requires a person' };
+    }
+    if ((plan.changes?.length ?? 0) === 0)
+        return { kind: 'ALREADY_READY' };
+    const applied = await read(['setup', 'apply', '--non-interactive', '--json']);
+    if (applied.error)
+        return { kind: 'FAILED', detail: `JAM setup apply 가 실패했다 — ${applied.error}` };
+    if (applied.requiresUserAction) {
+        return { kind: 'NEEDS_HUMAN', detail: applied.code ?? applied.status ?? 'JAM setup requires a person' };
+    }
+    return { kind: 'HEALED', changes: plan.changes?.length ?? 0 };
+}
+/** 사람이 읽는 한 줄. 무엇을 했는지·무엇이 남았는지가 여기 있어야 한다. */
+export function healLine(outcome) {
+    switch (outcome.kind) {
+        case 'ALREADY_READY':
+            return 'JAM: already set up for this project';
+        case 'HEALED':
+            return `JAM: repaired through its own setup (${outcome.changes} change${outcome.changes === 1 ? '' : 's'})`;
+        case 'NEEDS_HUMAN':
+            return `JAM: needs you — ${outcome.detail}. ASC does not sign in for you.`;
+        case 'FAILED':
+            return `JAM: ${outcome.detail}`;
+    }
+}

package/dist/adapters/service/launchd.d.ts

@@ -0,0 +1,12 @@
+import { type PersistentRuntimeAdapter, type ServiceCommand } from '../../core/distribution/persistent-runtime.ts';
+export declare const plistPath: (home?: string) => string;
+/**
+ * plist 본문. **내용이 곧 비교 기준이다** — 같으면 CURRENT, 다르면 STALE 이다.
+ * digest 를 따로 두지 않는 이유: 파일이 우리가 만들 내용과 같은지 보는 것이 더 정확하다.
+ */
+export declare function launchAgentPlist(command: ServiceCommand): string;
+export type LaunchdDeps = {
+    home?: string;
+    exec?: (command: string, args: readonly string[]) => Promise<void>;
+};
+export declare function launchdAdapter(deps?: LaunchdDeps): PersistentRuntimeAdapter;

package/dist/adapters/service/launchd.js

@@ -0,0 +1,80 @@
+// macOS — user LaunchAgent (설계 §4.3).
+//
+// root daemon 이 아니라 **사용자 것**이다. `~/Library/LaunchAgents/` 에 살고 로그인 이후에
+// 돈다. 그것이 이 계약의 경계이고, 그 위로 올리지 않는다 — 사람의 세션과 무관하게 도는
+// 것은 사용자가 켜지 않은 상시 프로세스이며 다른 종류의 결정이다.
+//
+// `StartInterval` 로 짧은 회차를 반복시킨다. 계속 도는 프로세스를 등록하지 않는 이유는
+// port 주석에 있다: 죽었을 때 되살리는 일을 OS 가 더 잘한다.
+import { execFile } from 'node:child_process';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { promisify } from 'node:util';
+import { SERVICE_LABEL, } from "../../core/distribution/persistent-runtime.js";
+const run = promisify(execFile);
+export const plistPath = (home = homedir()) => join(home, 'Library', 'LaunchAgents', `${SERVICE_LABEL}.plist`);
+/** XML 이스케이프. 경로에 `&` 가 있는 기계가 실제로 있다. */
+const xml = (value) => value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+/**
+ * plist 본문. **내용이 곧 비교 기준이다** — 같으면 CURRENT, 다르면 STALE 이다.
+ * digest 를 따로 두지 않는 이유: 파일이 우리가 만들 내용과 같은지 보는 것이 더 정확하다.
+ */
+export function launchAgentPlist(command) {
+    const args = [command.program, ...command.args].map((arg) => `    <string>${xml(arg)}</string>`).join('\n');
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${SERVICE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args}
+  </array>
+  <key>StartInterval</key>
+  <integer>${command.intervalSeconds}</integer>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>ProcessType</key>
+  <string>Background</string>
+</dict>
+</plist>
+`;
+}
+export function launchdAdapter(deps = {}) {
+    const home = deps.home ?? homedir();
+    const path = plistPath(home);
+    const exec = deps.exec ??
+        (async (command, args) => {
+            await run(command, [...args]);
+        });
+    return {
+        id: 'launchd',
+        async supported() {
+            return process.platform === 'darwin';
+        },
+        async status(command) {
+            const wanted = launchAgentPlist(command);
+            const existing = await readFile(path, 'utf8').catch(() => null);
+            if (existing === null)
+                return { kind: 'ABSENT' };
+            if (existing === wanted)
+                return { kind: 'CURRENT', detail: path };
+            // 우리 파일이 우리 내용과 다르다 — 경로나 간격이 바뀌었다는 뜻이다.
+            return { kind: 'STALE', detail: `${path} does not match the current runtime` };
+        },
+        async install(command) {
+            await mkdir(dirname(path), { recursive: true });
+            await writeFile(path, launchAgentPlist(command), 'utf8');
+            // 다시 읽히게 한다. 이미 없는 것을 unload 하는 것은 오류가 아니므로 삼킨다.
+            await exec('launchctl', ['unload', path]).catch(() => undefined);
+            await exec('launchctl', ['load', path]);
+        },
+        async uninstall() {
+            await exec('launchctl', ['unload', path]).catch(() => undefined);
+            // 우리가 만든 것만 지운다. 없으면 지울 것이 없다.
+            await rm(path, { force: true });
+        },
+    };
+}

package/dist/adapters/service/schtasks.d.ts

@@ -0,0 +1,16 @@
+import { type PersistentRuntimeAdapter, type ServiceCommand } from '../../core/distribution/persistent-runtime.ts';
+/** 작업 이름. `\` 없이 두면 루트 폴더에 만들어진다. */
+export declare const TASK_NAME = "com.asc-agent.runtime";
+/**
+ * `/TR` 에 들어갈 한 줄.
+ *
+ * schtasks 는 명령을 문자열 하나로 받는다 — 경로에 공백이 있으면 통째로 깨지므로
+ * 각 조각을 따옴표로 감싼다. 따옴표가 든 인자는 등록 자체를 깨뜨리므로 거른다.
+ */
+export declare function taskRunLine(command: ServiceCommand): string;
+/** 분 단위 반복. 1분 아래로는 Task Scheduler 가 받지 않는다. */
+export declare const taskMinutes: (intervalSeconds: number) => number;
+export type SchtasksDeps = {
+    exec?: (command: string, args: readonly string[]) => Promise<string>;
+};
+export declare function schtasksAdapter(deps?: SchtasksDeps): PersistentRuntimeAdapter;

package/dist/adapters/service/schtasks.js

@@ -0,0 +1,67 @@
+// Windows — 사용자 Scheduled Task (설계 §4.3).
+//
+// 시스템 서비스가 아니라 **로그인한 사용자의 작업**이다. `/RU` 없이 만들면 현재 사용자로
+// 등록되고, 그것이 이 계약의 경계다.
+//
+// 반복은 Task Scheduler 가 한다(`/SC MINUTE /MO n`). ASC 는 한 회차만 도는 명령을 준다.
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { SERVICE_LABEL, } from "../../core/distribution/persistent-runtime.js";
+const run = promisify(execFile);
+/** 작업 이름. `\` 없이 두면 루트 폴더에 만들어진다. */
+export const TASK_NAME = SERVICE_LABEL;
+/**
+ * `/TR` 에 들어갈 한 줄.
+ *
+ * schtasks 는 명령을 문자열 하나로 받는다 — 경로에 공백이 있으면 통째로 깨지므로
+ * 각 조각을 따옴표로 감싼다. 따옴표가 든 인자는 등록 자체를 깨뜨리므로 거른다.
+ */
+export function taskRunLine(command) {
+    const quote = (value) => `\\"${value}\\"`;
+    return [command.program, ...command.args].map(quote).join(' ');
+}
+/** 분 단위 반복. 1분 아래로는 Task Scheduler 가 받지 않는다. */
+export const taskMinutes = (intervalSeconds) => Math.max(1, Math.round(intervalSeconds / 60));
+export function schtasksAdapter(deps = {}) {
+    const exec = deps.exec ??
+        (async (command, args) => {
+            const { stdout } = await run(command, [...args]);
+            return stdout;
+        });
+    return {
+        id: 'schtasks',
+        async supported() {
+            return process.platform === 'win32';
+        },
+        async status(command) {
+            const query = await exec('schtasks', ['/Query', '/TN', TASK_NAME, '/FO', 'LIST', '/V']).catch(() => null);
+            // 조회가 실패하는 것은 대개 "없다"이다. 없는 것과 못 읽은 것을 구분할 방법이
+            // schtasks 에는 없으므로, 없는 쪽으로 읽고 install 이 다시 판정하게 둔다.
+            if (query === null)
+                return { kind: 'ABSENT' };
+            const wanted = taskRunLine(command).replace(/\\"/g, '"');
+            // 조회 출력에 우리 명령이 그대로 들어 있는가. 없으면 낡은 등록이다.
+            return query.includes(wanted)
+                ? { kind: 'CURRENT', detail: TASK_NAME }
+                : { kind: 'STALE', detail: `${TASK_NAME} runs a different command` };
+        },
+        async install(command) {
+            // `/F` 로 덮어쓴다 — 같은 이름의 우리 등록을 지금 형태로 수렴시키는 것이다.
+            await exec('schtasks', [
+                '/Create',
+                '/F',
+                '/TN',
+                TASK_NAME,
+                '/TR',
+                taskRunLine(command),
+                '/SC',
+                'MINUTE',
+                '/MO',
+                String(taskMinutes(command.intervalSeconds)),
+            ]);
+        },
+        async uninstall() {
+            await exec('schtasks', ['/Delete', '/TN', TASK_NAME, '/F']).catch(() => undefined);
+        },
+    };
+}

package/dist/adapters/service/systemd-user.d.ts

@@ -0,0 +1,15 @@
+import { type PersistentRuntimeAdapter, type ServiceCommand } from '../../core/distribution/persistent-runtime.ts';
+export declare const unitDir: (home?: string) => string;
+export declare const SERVICE_UNIT = "com.asc-agent.runtime.service";
+export declare const TIMER_UNIT = "com.asc-agent.runtime.timer";
+export declare function serviceUnit(command: ServiceCommand): string;
+export declare function timerUnit(command: ServiceCommand): string;
+export type SystemdDeps = {
+    home?: string;
+    exec?: (command: string, args: readonly string[]) => Promise<void>;
+    /** systemd --user 를 쓸 수 있는가. 테스트 주입점. */
+    available?: () => Promise<boolean>;
+};
+export declare function systemdUserAdapter(deps?: SystemdDeps): PersistentRuntimeAdapter;
+/** 이 기계에 맞는 adapter. 모르면 `null` — 없는 것을 있는 척하지 않는다. */
+export declare function serviceAdapterFor(platform: NodeJS.Platform): 'launchd' | 'schtasks' | 'systemd-user' | null;

package/dist/adapters/service/systemd-user.js

@@ -0,0 +1,95 @@
+// Linux — systemd --user (설계 §4.3).
+//
+// 사용자 세션에 묶인다. **lingering 을 조용히 켜지 않는다** — 그것은 "로그아웃해도 돈다"는
+// 뜻이고, 사용자가 하지 않은 결정이다. 필요해지면 사람이 명시적으로 켠다.
+//
+// timer 가 주기를 갖고 service 가 한 회차를 돈다. 계속 도는 프로세스를 두지 않는 이유는
+// port 주석과 같다.
+import { execFile } from 'node:child_process';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { SERVICE_LABEL, } from "../../core/distribution/persistent-runtime.js";
+const run = promisify(execFile);
+export const unitDir = (home = homedir()) => join(home, '.config', 'systemd', 'user');
+export const SERVICE_UNIT = `${SERVICE_LABEL}.service`;
+export const TIMER_UNIT = `${SERVICE_LABEL}.timer`;
+/** systemd 인자 인용. 공백이 든 경로가 통째로 깨지지 않게 한다. */
+const quote = (value) => `"${value.replace(/(["\\])/g, '\\$1')}"`;
+export function serviceUnit(command) {
+    return `[Unit]
+Description=ASC persistent runtime
+
+[Service]
+Type=oneshot
+ExecStart=${[command.program, ...command.args].map(quote).join(' ')}
+`;
+}
+export function timerUnit(command) {
+    return `[Unit]
+Description=ASC persistent runtime schedule
+
+[Timer]
+OnBootSec=${command.intervalSeconds}
+OnUnitActiveSec=${command.intervalSeconds}
+Unit=${SERVICE_UNIT}
+
+[Install]
+WantedBy=timers.target
+`;
+}
+export function systemdUserAdapter(deps = {}) {
+    const home = deps.home ?? homedir();
+    const dir = unitDir(home);
+    const exec = deps.exec ??
+        (async (command, args) => {
+            await run(command, [...args]);
+        });
+    const available = deps.available ??
+        (async () => {
+            if (process.platform !== 'linux')
+                return false;
+            // 컨테이너처럼 user bus 가 없는 자리가 흔하다 — 있는 척하지 않는다.
+            return run('systemctl', ['--user', 'show-environment'])
+                .then(() => true)
+                .catch(() => false);
+        });
+    return {
+        id: 'systemd-user',
+        supported: available,
+        async status(command) {
+            const service = await readFile(join(dir, SERVICE_UNIT), 'utf8').catch(() => null);
+            const timer = await readFile(join(dir, TIMER_UNIT), 'utf8').catch(() => null);
+            if (service === null || timer === null)
+                return { kind: 'ABSENT' };
+            return service === serviceUnit(command) && timer === timerUnit(command)
+                ? { kind: 'CURRENT', detail: dir }
+                : { kind: 'STALE', detail: `${dir} does not match the current runtime` };
+        },
+        async install(command) {
+            await mkdir(dir, { recursive: true });
+            await writeFile(join(dir, SERVICE_UNIT), serviceUnit(command), 'utf8');
+            await writeFile(join(dir, TIMER_UNIT), timerUnit(command), 'utf8');
+            await exec('systemctl', ['--user', 'daemon-reload']);
+            await exec('systemctl', ['--user', 'enable', '--now', TIMER_UNIT]);
+        },
+        async uninstall() {
+            await exec('systemctl', ['--user', 'disable', '--now', TIMER_UNIT]).catch(() => undefined);
+            // 우리가 만든 것만 지운다.
+            await rm(join(dir, TIMER_UNIT), { force: true });
+            await rm(join(dir, SERVICE_UNIT), { force: true });
+            await exec('systemctl', ['--user', 'daemon-reload']).catch(() => undefined);
+        },
+    };
+}
+/** 이 기계에 맞는 adapter. 모르면 `null` — 없는 것을 있는 척하지 않는다. */
+export function serviceAdapterFor(platform) {
+    if (platform === 'darwin')
+        return 'launchd';
+    if (platform === 'win32')
+        return 'schtasks';
+    if (platform === 'linux')
+        return 'systemd-user';
+    return null;
+}