@asc-agent/runtime 0.1.0

package/dist/adapters/gitlab/adapter.js

@@ -0,0 +1,117 @@
+// GitLab Adapter 계약 — describe / discover / probe (C-09 §5).
+//
+// GitHub adapter와 같은 세 함수를 갖되 내용은 다르다. 그 "같은 모양 다른 내용"이
+// Adapter 계약이 실제로 계약이라는 증거다.
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { GitLabClient, discoverToken, encodeProject } from "./client.js";
+const run = promisify(execFile);
+const PROVIDES = [
+    'observe.delta',
+    'inventory.enumerate',
+    'context.resource',
+    'context.thread',
+    'context.change',
+];
+/**
+ * 이 host는 다른 adapter가 맡는다. 여기서 후보로 잡으면 같은 remote를 둘이 주장한다.
+ *
+ * 목록이 아니라 **판정**이므로 짧게 유지한다 — 여기가 길어지기 시작하면 그건 adapter가
+ * provider 목록을 아는 물건이 됐다는 뜻이다.
+ */
+const CLAIMED_ELSEWHERE = new Set(['github.com']);
+export class GitLabAdapter {
+    #listRemotes;
+    #findToken;
+    #reach;
+    #host;
+    /**
+     * 후보를 찾을 때 본 host. probe가 어디로 물어봐야 하는지 알아야 하는데 후보 자체는
+     * 경로만 들고 있다 — Core 타입에 자리를 만드는 대신 여기 둔다.
+     *
+     * discover와 probe를 같은 인스턴스가 이어서 부르는 것이 조립 순서다(composition).
+     * 그렇지 않은 호출자는 `ASC_GITLAB_URL` 로 명시하면 된다.
+     */
+    #endpoints = new Map();
+    constructor(deps = {}) {
+        this.#listRemotes = deps.listRemotes ?? defaultListRemotes;
+        this.#findToken = deps.findToken ?? discoverToken;
+        this.#reach = deps.reach;
+        this.#host = deps.host;
+    }
+    describe() {
+        return {
+            id: 'gitlab',
+            version: '1',
+            provides: PROVIDES,
+            requiresCredential: ['ASC_GITLAB_TOKEN | GITLAB_TOKEN'],
+            prerequisites: ['git remote 가 이 host를 가리켜야 한다'],
+        };
+    }
+    /**
+     * remote **전부**를 본다. `origin` 하나만 보면 origin이 코드 정본이 아닌 프로젝트에서
+     * 아무것도 못 찾는다 (지시 §13).
+     *
+     * host를 미리 알고 있지 않다 — 자체 호스팅이 흔하고, 주소를 코드에 박으면 그 프로젝트
+     * 하나를 위한 adapter가 된다. 대신 **다른 adapter가 맡는 host만 비켜** 나머지를 후보로
+     * 올린다. 후보는 추측이 아니라 후보이며, 실제로 되는지는 probe가 정한다.
+     */
+    async discover(context) {
+        const remotes = await this.#listRemotes(context.projectRoot).catch(() => []);
+        const override = this.#host ?? context.env?.ASC_GITLAB_HOST;
+        const found = new Map();
+        for (const url of remotes) {
+            const parsed = parseRemote(url);
+            if (!parsed)
+                continue;
+            if (override ? parsed.host !== override : CLAIMED_ELSEWHERE.has(parsed.host))
+                continue;
+            // 하위 그룹이 흔하다 — `group/sub/project` 를 통째로 자원 이름으로 쓴다.
+            this.#endpoints.set(parsed.project, `https://${parsed.host}/api/v4`);
+            found.set(parsed.project, {
+                adapterId: 'gitlab',
+                resource: parsed.project,
+                provides: PROVIDES,
+                discoveredBy: `git remote (${parsed.host})`,
+            });
+        }
+        return [...found.values()];
+    }
+    async probe(candidate, context) {
+        const token = this.#findToken(context.env);
+        if (!token) {
+            return { state: 'UNCONFIGURED', detail: '토큰이 없다 — ASC_GITLAB_TOKEN 또는 GITLAB_TOKEN 을 두어라' };
+        }
+        const baseUrl = context.env?.ASC_GITLAB_URL ?? this.#endpoints.get(candidate.resource);
+        const reach = this.#reach ?? ((project, secret) => defaultReach(project, secret, baseUrl));
+        const result = await reach(candidate.resource, token);
+        return result.ok
+            ? { state: 'AVAILABLE', provides: candidate.provides }
+            : { state: 'UNAVAILABLE', detail: result.detail ?? '프로젝트에 닿지 못했다' };
+    }
+    /** 이 후보가 어느 주소를 가리키는지. composition이 Port를 만들 때 같은 값을 써야 한다. */
+    endpointFor(resource) {
+        return this.#endpoints.get(resource);
+    }
+}
+export function parseRemote(url) {
+    const ssh = /^[^@]+@([^:]+):(.+?)(?:\.git)?$/.exec(url.trim());
+    if (ssh)
+        return { host: ssh[1], project: ssh[2] };
+    const https = /^https?:\/\/([^/]+)\/(.+?)(?:\.git)?$/.exec(url.trim());
+    if (https)
+        return { host: https[1], project: https[2] };
+    return null;
+}
+async function defaultListRemotes(projectRoot) {
+    const { stdout } = await run('git', ['-C', projectRoot, 'remote', '-v']);
+    return stdout
+        .split('\n')
+        .map((line) => line.split(/\s+/)[1])
+        .filter((url) => Boolean(url));
+}
+async function defaultReach(project, token, baseUrl) {
+    const client = new GitLabClient({ token, ...(baseUrl ? { baseUrl } : {}) });
+    const response = await client.get(`/projects/${encodeProject(project)}`);
+    return response.ok ? { ok: true } : { ok: false, detail: `HTTP ${response.status}` };
+}

package/dist/adapters/gitlab/client.d.ts

@@ -0,0 +1,30 @@
+export type Fetch = typeof globalThis.fetch;
+export type GitLabClientDeps = {
+    token: string;
+    fetch?: Fetch;
+    /** self-hosted가 흔하다. 기본값은 공개 인스턴스. */
+    baseUrl?: string;
+};
+export type GitLabResponse<T> = {
+    ok: boolean;
+    status: number;
+    data: T | null;
+    /** 다음 페이지 번호. 없으면 끝이다. */
+    nextPage?: string;
+    error?: string;
+};
+/** 환경변수에서만 찾는다. 값을 파일이나 Profile에 남기지 않는다. */
+export declare function discoverToken(env?: NodeJS.ProcessEnv): string | null;
+export declare class GitLabClient {
+    #private;
+    constructor(deps: GitLabClientDeps);
+    get<T>(path: string): Promise<GitLabResponse<T>>;
+}
+/** `group/sub/project!19` 또는 `group/project#7` 을 쪼갠다. */
+export declare function parseRef(reference: string): {
+    project: string;
+    kind: 'change' | 'issue';
+    iid: number;
+} | null;
+/** 경로를 URL 조각으로. GitLab은 프로젝트 경로를 통째로 인코딩해 받는다. */
+export declare const encodeProject: (project: string) => string;

package/dist/adapters/gitlab/client.js

@@ -0,0 +1,47 @@
+// GitLab REST 최소 클라이언트.
+//
+// GitHub 쪽과 같은 모양을 일부러 유지한다 — 두 adapter가 비슷하게 생겼다는 사실이
+// "Core가 바뀌지 않는다"를 보여주는 근거의 일부다. 토큰은 여기서 만들지도 저장하지도
+// 않는다 (OM §4.5).
+//
+// fetch를 주입받는 이유는 테스트 때문이다. 실 네트워크에 기대는 테스트는 남의 사정으로
+// 깨지고, 그러면 아무도 안 보게 된다.
+/** 환경변수에서만 찾는다. 값을 파일이나 Profile에 남기지 않는다. */
+export function discoverToken(env = process.env) {
+    return env.ASC_GITLAB_TOKEN ?? env.GITLAB_TOKEN ?? null;
+}
+export class GitLabClient {
+    #token;
+    #fetch;
+    #baseUrl;
+    constructor(deps) {
+        this.#token = deps.token;
+        this.#fetch = deps.fetch ?? globalThis.fetch;
+        this.#baseUrl = deps.baseUrl ?? 'https://gitlab.com/api/v4';
+    }
+    async get(path) {
+        const response = await this.#fetch(`${this.#baseUrl}${path}`, {
+            headers: { accept: 'application/json', 'private-token': this.#token },
+        });
+        const nextPage = response.headers.get('x-next-page') ?? undefined;
+        if (!response.ok) {
+            return { ok: false, status: response.status, data: null, error: `HTTP ${response.status}` };
+        }
+        return {
+            ok: true,
+            status: response.status,
+            data: (await response.json()),
+            // 빈 문자열은 "다음 없음"이다 — 그대로 실어 보내면 0페이지를 영원히 돈다.
+            ...(nextPage ? { nextPage } : {}),
+        };
+    }
+}
+/** `group/sub/project!19` 또는 `group/project#7` 을 쪼갠다. */
+export function parseRef(reference) {
+    const match = /^(.+?)([!#])(\d+)$/.exec(reference.trim());
+    if (!match)
+        return null;
+    return { project: match[1], kind: match[2] === '!' ? 'change' : 'issue', iid: Number(match[3]) };
+}
+/** 경로를 URL 조각으로. GitLab은 프로젝트 경로를 통째로 인코딩해 받는다. */
+export const encodeProject = (project) => encodeURIComponent(project);

package/dist/adapters/gitlab/ports.d.ts

@@ -0,0 +1,40 @@
+import type { ChangeContextPort, ChangeSummary } from '../../ports/change-context.ts';
+import type { Cursor, EventBatch, EventSource } from '../../ports/event-source.ts';
+import type { InventoryPage, InventoryPort, InventoryQuery } from '../../ports/inventory.ts';
+import type { CommentQuery, ContextComment, ResourceContextPort, ResourceSnapshot } from '../../ports/resource-context.ts';
+import { type GitLabClient } from './client.ts';
+export type GitLabDeps = {
+    client: GitLabClient;
+    /** `group/sub/project`. */
+    project: string;
+    perPage?: number;
+};
+declare abstract class GitLabBase {
+    readonly id: string;
+    protected client: GitLabClient;
+    protected project: string;
+    protected perPage: number;
+    constructor(deps: GitLabDeps);
+    protected path(reference: string): string | null;
+}
+/**
+ * 할 일 목록(todo)으로 증분을 받는다. GitHub의 알림과 같은 자리이고, 같은 한계를 갖는다 —
+ * 지정이 빠지면 오지 않는다. 그래서 Inventory가 따로 있다.
+ */
+export declare class GitLabEventSource extends GitLabBase implements EventSource {
+    readonly id = "gitlab-todo";
+    cursorFrom(since: string): Cursor;
+    drain(cursor: Cursor): Promise<EventBatch>;
+}
+/** 상태 무관 열거. 이슈와 변경요청을 각각 받아 합친다 — GitLab은 두 목록이 따로다. */
+export declare class GitLabInventory extends GitLabBase implements InventoryPort {
+    enumerate(query: InventoryQuery, cursor?: string): Promise<InventoryPage>;
+}
+export declare class GitLabResourceContext extends GitLabBase implements ResourceContextPort {
+    getResource(reference: string): Promise<ResourceSnapshot>;
+    getComments(reference: string, query?: CommentQuery): Promise<ContextComment[]>;
+}
+export declare class GitLabChangeContext extends GitLabBase implements ChangeContextPort {
+    getChange(reference: string): Promise<ChangeSummary>;
+}
+export {};

package/dist/adapters/gitlab/ports.js

@@ -0,0 +1,186 @@
+// GitLab Adapter — EventSource · Inventory · ResourceContext · ChangeContext.
+//
+// 이 adapter의 목적은 GitLab 지원 자체가 아니라 **같은 Core가 다른 adapter를 Binding
+// 교체만으로 소비하는지** 보이는 것이다 (C-09 §9). 그래서 일부러 다르게 생긴 것을 고른다:
+//
+//   참조 문법   `group/sub/proj!19` (변경요청) · `group/proj#7` (이슈)
+//   event kind  `todo:` · `note:`  — GitHub의 `notification:` 과 다르다
+//   상태 어휘   opened / closed / merged
+//
+// Core가 이 셋 중 무엇도 해석하지 않는다는 것이 Swap Gate의 내용이다.
+import { encodeProject, parseRef } from "./client.js";
+const marker = (parts) => parts.map((p) => (p === undefined ? '' : String(p))).join('|');
+class GitLabBase {
+    // 하위 클래스가 좁혀 쓴다 — EventSource만 `gitlab-todo` 로 자기 통로를 밝힌다.
+    id = 'gitlab';
+    client;
+    project;
+    perPage;
+    constructor(deps) {
+        this.client = deps.client;
+        this.project = deps.project;
+        this.perPage = deps.perPage ?? 50;
+    }
+    path(reference) {
+        const ref = parseRef(reference);
+        if (!ref)
+            return null;
+        const kind = ref.kind === 'change' ? 'merge_requests' : 'issues';
+        return `/projects/${encodeProject(ref.project)}/${kind}/${ref.iid}`;
+    }
+}
+/**
+ * 할 일 목록(todo)으로 증분을 받는다. GitHub의 알림과 같은 자리이고, 같은 한계를 갖는다 —
+ * 지정이 빠지면 오지 않는다. 그래서 Inventory가 따로 있다.
+ */
+export class GitLabEventSource extends GitLabBase {
+    id = 'gitlab-todo';
+    cursorFrom(since) {
+        return JSON.stringify({ since });
+    }
+    async drain(cursor) {
+        const parsed = cursor ? JSON.parse(cursor) : {};
+        const params = new URLSearchParams({ per_page: String(this.perPage) });
+        if (parsed.page)
+            params.set('page', parsed.page);
+        const response = await this.client.get(`/todos?${params}`);
+        if (!response.ok || !response.data)
+            return { events: [], cursor };
+        const events = [];
+        for (const todo of response.data) {
+            // 기준선 이전 것은 버린다. provider가 since를 지원하지 않아 여기서 거른다 —
+            // 겹쳐 읽고 key로 중복을 거르는 편이 놓치는 것보다 싸다 (OM §10.5).
+            if (parsed.since && todo.updated_at < parsed.since)
+                continue;
+            const project = todo.project?.path_with_namespace ?? this.project;
+            const separator = todo.target_type === 'MergeRequest' ? '!' : '#';
+            events.push({
+                eventKey: `todo:${todo.id}:${todo.updated_at}`,
+                detectedAt: todo.updated_at,
+                reference: `${project}${separator}${todo.target?.iid ?? 0}`,
+                ...(todo.author?.username ? { hints: { actors: [todo.author.username] } } : {}),
+                raw: {
+                    kind: 'todo',
+                    // provider 어휘 그대로 둔다 — Generic Signal로 옮기는 것은 Profile의 몫이다 (OM §10.6).
+                    reason: todo.action_name,
+                    title: todo.target?.title,
+                    body: todo.body,
+                },
+            });
+        }
+        const next = response.nextPage
+            ? JSON.stringify({ ...(parsed.since ? { since: parsed.since } : {}), page: response.nextPage })
+            : JSON.stringify({ since: events.at(-1)?.detectedAt ?? parsed.since });
+        return { events, cursor: next, ...(response.nextPage ? { hasMore: true } : {}) };
+    }
+}
+/** 상태 무관 열거. 이슈와 변경요청을 각각 받아 합친다 — GitLab은 두 목록이 따로다. */
+export class GitLabInventory extends GitLabBase {
+    async enumerate(query, cursor) {
+        const page = cursor ?? '1';
+        const base = new URLSearchParams({ per_page: String(this.perPage), page, scope: 'all' });
+        if (query.updatedSince)
+            base.set('updated_after', query.updatedSince);
+        const wanted = new Set(query.kinds ?? []);
+        const items = [];
+        let next;
+        for (const [kind, path, separator] of [
+            ['issue', 'issues', '#'],
+            ['change', 'merge_requests', '!'],
+        ]) {
+            if (wanted.size > 0 && !wanted.has(kind))
+                continue;
+            const response = await this.client.get(`/projects/${encodeProject(this.project)}/${path}?${base}`);
+            // 한 갈래라도 못 읽었으면 완주했다고 말할 수 없다.
+            if (!response.ok || !response.data)
+                return { items, complete: false };
+            if (response.nextPage)
+                next = response.nextPage;
+            for (const row of response.data) {
+                items.push({
+                    reference: `${this.project}${separator}${row.iid}`,
+                    state: row.state,
+                    updatedAt: row.updated_at,
+                    revisionMarker: marker([row.updated_at, row.sha, row.state, row.user_notes_count]),
+                    title: row.title,
+                    assignees: (row.assignees ?? []).map((a) => a.username),
+                    labels: row.labels ?? [],
+                });
+            }
+        }
+        return { items, ...(next ? { next } : {}), complete: next === undefined };
+    }
+}
+export class GitLabResourceContext extends GitLabBase {
+    async getResource(reference) {
+        const path = this.path(reference);
+        if (!path)
+            return missing(reference);
+        const response = await this.client.get(path);
+        if (!response.ok || !response.data)
+            return missing(reference);
+        const row = response.data;
+        return {
+            reference,
+            state: row.state,
+            title: row.title,
+            ...(row.description ? { body: row.description } : {}),
+            ...(row.author?.username ? { author: row.author.username } : {}),
+            assignees: (row.assignees ?? []).map((a) => a.username),
+            labels: row.labels ?? [],
+            updatedAt: row.updated_at,
+            revisionMarker: marker([row.updated_at, row.sha, row.state, row.user_notes_count]),
+        };
+    }
+    async getComments(reference, query = {}) {
+        const path = this.path(reference);
+        if (!path)
+            return [];
+        const params = new URLSearchParams({ per_page: String(query.limit ?? 20), sort: 'desc' });
+        const response = await this.client.get(`${path}/notes?${params}`);
+        if (!response.ok || !response.data)
+            return [];
+        return response.data
+            .filter((note) => !query.since || note.updated_at >= query.since)
+            .map((note) => ({
+            id: String(note.id),
+            author: note.author?.username ?? '(unknown)',
+            at: note.updated_at ?? note.created_at,
+            body: note.body ?? '',
+            // 여기는 resolvable 여부를 알려준다 — 아는 것만 적는다.
+            ...(note.resolvable ? { unresolved: note.resolved !== true } : {}),
+        }));
+    }
+}
+export class GitLabChangeContext extends GitLabBase {
+    async getChange(reference) {
+        const ref = parseRef(reference);
+        if (!ref || ref.kind !== 'change') {
+            return { reference, changedPaths: [], revisionMarker: '', missing: true };
+        }
+        const base = `/projects/${encodeProject(ref.project)}/merge_requests/${ref.iid}`;
+        const detail = await this.client.get(base);
+        if (!detail.ok || !detail.data)
+            return { reference, changedPaths: [], revisionMarker: '', missing: true };
+        const changes = await this.client.get(`${base}/changes`);
+        const paths = (changes.data?.changes ?? []).map((c) => c.new_path ?? c.old_path ?? '').filter(Boolean);
+        return {
+            reference,
+            changedPaths: paths,
+            // provider가 "다 못 준다"고 말해 준다. 그 사실을 숨기면 "내 영역은 안 바뀌었다"는
+            // 틀린 판정이 나온다.
+            ...(changes.data?.overflow || !changes.ok ? { truncated: true } : {}),
+            ...(detail.data.sha ? { revisions: [detail.data.sha] } : {}),
+            revisionMarker: marker([detail.data.updated_at, detail.data.sha, detail.data.state]),
+            ...(detail.data.detailed_merge_status ? { reviewState: detail.data.detailed_merge_status } : {}),
+        };
+    }
+}
+const missing = (reference) => ({
+    reference,
+    state: 'unknown',
+    title: '',
+    updatedAt: '',
+    revisionMarker: '',
+    missing: true,
+});

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

@@ -0,0 +1,53 @@
+import type { AdapterDescriptor, BindingCandidate } from '../../core/binding/types.ts';
+import type { Adapter, DiscoveryContext, ProbeResult, RuntimeStatus } from '../../ports/adapter.ts';
+export type JamAdapterDeps = {
+    /**
+     * JAM 실행 명령. 아직 패키지로 배포되지 않아 경로가 환경마다 다르다 —
+     * 그래서 환경에서 받고, 값을 문서·Profile·저장소에 남기지 않는다.
+     */
+    command?: string;
+    args?: readonly string[];
+    /** 상태 조회 통로. 테스트가 실제 프로세스를 띄우지 않기 위한 주입점. */
+    authStatus?: (context: DiscoveryContext) => Promise<AuthStatus>;
+    /** 선언 파일 읽기 통로. */
+    readDeclaration?: (projectRoot: string) => Promise<string | null>;
+};
+/** `jam auth status --json` 의 응답. **토큰 값은 여기 오지 않는다.** */
+export type AuthStatus = {
+    status?: 'configured' | 'not_configured';
+    code?: string;
+    source?: string;
+    /** 어느 인스턴스인지. 사람이 "맞는 곳인가"를 확인하는 데 쓴다. */
+    baseUrl?: string;
+    /** 실행 자체가 안 됐을 때의 이유. */
+    error?: string;
+};
+/**
+ * 어떻게 실행할 것인가.
+ *
+ * 아직 패키지로 배포되지 않아 환경마다 형태가 다르다 — 실행 파일일 수도, 스크립트 경로일
+ * 수도 있다. 스크립트면 지금 도는 것과 같은 런타임으로 부른다.
+ *
+ * composition도 같은 규칙을 써야 probe와 실제 호출이 같은 곳을 가리킨다.
+ */
+export declare function resolveJamCommand(env: NodeJS.ProcessEnv | undefined, fallbackCommand?: string, fallbackArgs?: readonly string[]): {
+    command: string;
+    args: string[];
+};
+/** `project.yaml` 에서 key만 꺼낸다. YAML 파서를 들이지 않는다 — 읽을 것이 한 줄이다. */
+export declare function parseProjectKey(text: string): string | null;
+export declare class JamAdapter implements Adapter {
+    #private;
+    constructor(deps?: JamAdapterDeps);
+    describe(): AdapterDescriptor;
+    /**
+     * 선언 파일이 있을 때만 후보를 만든다.
+     *
+     * 다른 저장소의 선언이나 코드 저장소 이름에서 키를 **추측하지 않는다.** 이름이 비슷하다는
+     * 것은 연결됐다는 뜻이 아니고, 틀린 연결은 없는 연결보다 나쁘다.
+     */
+    discover(context: DiscoveryContext): Promise<BindingCandidate[]>;
+    probe(candidate: BindingCandidate, context: DiscoveryContext): Promise<ProbeResult>;
+    /** 프로젝트와 무관하게 "도구가 지금 쓸 수 있는가". binding 유무와 별개 사실이다. */
+    runtime(context: DiscoveryContext): Promise<RuntimeStatus>;
+}

package/dist/adapters/jam/adapter.js

@@ -0,0 +1,144 @@
+// JAM Adapter 계약 — describe / discover / probe / runtime.
+//
+// 이 adapter가 지키는 선 하나: **자격을 대신 다루지 않는다.** JAM은 사람이 직접 로그인하게
+// 설계돼 있고, 에이전트에게는 "됐는지 아닌지"만 알려 준다. ASC가 토큰을 받아 넘기거나
+// 로그인을 대신 실행하면 그 설계를 우회하는 것이다 — 하지 않는다.
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+const run = promisify(execFile);
+/**
+ * 실제로 되는 것만 적는다 (C-09 §1.1).
+ *
+ * 빠진 둘에 이유가 있다:
+ *   context.history  provider가 변경 이력을 주지 않는다 — 요청 경로 자체가 없다
+ *
+ * `observe.delta` 는 연다. **푸시가 있다는 뜻이 아니다** — C-07 §1.1이 Delta를
+ * "webhook / incremental polling / provider notification / updated-since" 로 정의하고
+ * 그 안에 시각 기준 증분 조회를 명시적으로 포함한다. JAM에는 webhook이 없고, 여기서
+ * 여는 것은 `updated >= watermark` 조회다 (adapters/jam/event-source.ts).
+ * push와 같은 말로 쓰면 "실시간이다"라는 잘못된 기대가 생기므로 그 구분을 여기 남긴다.
+ */
+const PROVIDES = [
+    'observe.delta',
+    'inventory.enumerate',
+    'context.resource',
+    'context.thread',
+];
+/** 프로젝트가 어느 작업 항목 묶음에 붙어 있는지 선언하는 파일. 없으면 붙어 있지 않은 것이다. */
+const DECLARATION = join('.jira-agent', 'project.yaml');
+/**
+ * 어떻게 실행할 것인가.
+ *
+ * 아직 패키지로 배포되지 않아 환경마다 형태가 다르다 — 실행 파일일 수도, 스크립트 경로일
+ * 수도 있다. 스크립트면 지금 도는 것과 같은 런타임으로 부른다.
+ *
+ * composition도 같은 규칙을 써야 probe와 실제 호출이 같은 곳을 가리킨다.
+ */
+export function resolveJamCommand(env, fallbackCommand = 'jam', fallbackArgs = []) {
+    const path = env?.ASC_JAM_PATH;
+    if (!path)
+        return { command: fallbackCommand, args: [...fallbackArgs] };
+    return path.endsWith('.js') || path.endsWith('.mjs')
+        ? { command: process.execPath, args: [path] }
+        : { command: path, args: [] };
+}
+/** `project.yaml` 에서 key만 꺼낸다. YAML 파서를 들이지 않는다 — 읽을 것이 한 줄이다. */
+export function parseProjectKey(text) {
+    const match = /^\s*key:\s*["']?([A-Za-z][A-Za-z0-9_]*)["']?\s*$/m.exec(text);
+    return match ? match[1] : null;
+}
+export class JamAdapter {
+    #command;
+    #args;
+    #authStatus;
+    #readDeclaration;
+    constructor(deps = {}) {
+        this.#command = deps.command ?? 'jam';
+        this.#args = deps.args ?? [];
+        this.#authStatus = deps.authStatus;
+        this.#readDeclaration = deps.readDeclaration ?? defaultRead;
+    }
+    describe() {
+        return {
+            id: 'jam',
+            version: '1',
+            provides: PROVIDES,
+            // 자격이 필요하다는 사실과 **사람이 해야 한다는 사실**까지. 값은 오지 않는다.
+            requiresCredential: ['사람이 직접 `jam auth login` — ASC가 대신 로그인하지 않는다'],
+            prerequisites: [
+                '프로젝트 루트에 .jira-agent/project.yaml 이 있어야 한다',
+                'JAM 실행 경로를 ASC_JAM_PATH 로 알려 줘야 한다 (아직 패키지로 배포되지 않았다)',
+            ],
+        };
+    }
+    /**
+     * 선언 파일이 있을 때만 후보를 만든다.
+     *
+     * 다른 저장소의 선언이나 코드 저장소 이름에서 키를 **추측하지 않는다.** 이름이 비슷하다는
+     * 것은 연결됐다는 뜻이 아니고, 틀린 연결은 없는 연결보다 나쁘다.
+     */
+    async discover(context) {
+        const text = await this.#readDeclaration(context.projectRoot);
+        if (!text)
+            return [];
+        const key = parseProjectKey(text);
+        if (!key)
+            return [];
+        return [{ adapterId: 'jam', resource: key, provides: PROVIDES, discoveredBy: DECLARATION }];
+    }
+    async probe(candidate, context) {
+        const status = await this.#status(context);
+        if (status.state !== 'AVAILABLE')
+            return { state: status.state, ...(status.detail ? { detail: status.detail } : {}) };
+        return { state: 'AVAILABLE', provides: candidate.provides };
+    }
+    /** 프로젝트와 무관하게 "도구가 지금 쓸 수 있는가". binding 유무와 별개 사실이다. */
+    async runtime(context) {
+        return this.#status(context);
+    }
+    async #status(context) {
+        const read = this.#authStatus ?? ((ctx) => this.#defaultAuthStatus(ctx));
+        const status = await read(context).catch((error) => ({ error: String(error) }));
+        if (status.error) {
+            return { state: 'UNAVAILABLE', detail: `JAM을 실행하지 못했다 — ${status.error}` };
+        }
+        if (status.status === 'configured') {
+            return { state: 'AVAILABLE', ...(status.baseUrl ? { detail: `연결 대상 ${status.baseUrl}` } : {}) };
+        }
+        // 설정이 안 된 것은 고장이 아니다. 사람이 할 일이 남았다는 뜻이고, 그 일을 알려 준다.
+        return {
+            state: 'UNCONFIGURED',
+            detail: '자격이 없다 — 사람이 직접 `jam auth login` 을 실행해야 한다 (ASC가 대신하지 않는다)',
+        };
+    }
+    async #defaultAuthStatus(context) {
+        const { command, args } = resolveJamCommand(context.env, this.#command, this.#args);
+        try {
+            const { stdout } = await run(command, [...args, 'auth', 'status', '--json']);
+            return JSON.parse(stdout);
+        }
+        catch (error) {
+            // 실행 실패와 "자격 없음"을 합치지 않는다. 전자는 설치·경로 문제다.
+            const stdout = error.stdout;
+            if (stdout) {
+                try {
+                    return JSON.parse(stdout);
+                }
+                catch {
+                    // 아래로 떨어뜨린다
+                }
+            }
+            return { error: String(error.message ?? error).slice(0, 200) };
+        }
+    }
+}
+async function defaultRead(projectRoot) {
+    try {
+        return await readFile(join(projectRoot, DECLARATION), 'utf8');
+    }
+    catch {
+        return null;
+    }
+}

package/dist/adapters/jam/event-source.d.ts

@@ -0,0 +1,28 @@
+import type { InventoryPort } from '../../ports/inventory.ts';
+import type { Cursor, EventBatch, EventSource } from '../../ports/event-source.ts';
+/**
+ * 분 단위 정밀도를 덮는 겹침. JamInventory의 JQL 변환이 쓰는 값과 같은 이유로 60초다 —
+ * 한쪽만 겹치면 겹치지 않은 쪽이 조용히 놓친다.
+ */
+export declare const OVERLAP_MS = 60000;
+export type JamEventSourceDeps = {
+    inventory: InventoryPort;
+    /** 이 통로의 이름. 관측 기록이 사는 scope가 이 값으로 정해진다. */
+    id?: string;
+    now?: () => string;
+};
+export declare class JamEventSource implements EventSource {
+    #private;
+    readonly id: string;
+    constructor(deps: JamEventSourceDeps);
+    /** "지금부터 보겠다". 처음 붙인 프로젝트의 과거를 통째로 긁으면 그 자체가 잡음이다. */
+    cursorFrom(since: string): Cursor;
+    /**
+     * cursor 이후로 바뀐 것을 사건으로 흘린다.
+     *
+     * **cursor는 성공한 회차에만 전진한다.** 목록을 끝까지 못 봤으면(`complete=false`)
+     * 그 회차의 최대 시각으로 올리지 않는다 — 못 본 구간을 본 것으로 표시하는 셈이 된다
+     * (C-07 §1.5).
+     */
+    drain(cursor: Cursor): Promise<EventBatch>;
+}