toolcraft 0.0.11 → 0.0.13

package/node_modules/@poe-code/process-runner/dist/types.d.ts

@@ -0,0 +1,180 @@
+import type { Readable, Writable } from "node:stream";
+export interface RunHandle {
+    readonly pid: number | null;
+    readonly stdout: Readable | null;
+    readonly stderr: Readable | null;
+    readonly stdin: Writable | null;
+    readonly result: Promise<RunResult>;
+    kill(signal?: NodeJS.Signals): void;
+}
+export interface RunResult {
+    exitCode: number;
+}
+export interface RunSpec {
+    command: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    stdin?: "pipe" | "inherit" | "ignore";
+    stdout?: "pipe" | "inherit";
+    stderr?: "pipe" | "inherit";
+    tty?: boolean;
+    signal?: AbortSignal;
+}
+export interface Runner {
+    exec(spec: RunSpec): RunHandle;
+    readonly name: string;
+}
+export interface HostRunnerOptions {
+    detached?: boolean;
+}
+export type ExecutionEnvType = "host" | "docker" | "e2b";
+export type JobStatus = "running" | "exited" | "killed" | "lost";
+export interface ExecutionEnvFactory {
+    readonly type: ExecutionEnvType;
+    readonly supportsDetach?: boolean;
+    open(spec: OpenSpec): Promise<OpenedEnv>;
+    attach(envId: string, context?: AttachedJobContext): Promise<OpenedEnv>;
+}
+export interface OpenSpec {
+    cwd: string;
+    runtime: unknown;
+    runner?: unknown;
+    state?: ExecutionState;
+    hostRunner?: Runner;
+    env: Record<string, string>;
+    uploadIgnoreFiles: string[];
+    jobLabel: {
+        tool: string;
+        argv: string[];
+    };
+    execution?: {
+        wrapForLogTee?: boolean;
+        stdin?: RunSpec["stdin"];
+        stdout?: RunSpec["stdout"];
+        stderr?: RunSpec["stderr"];
+        env?: RunSpec["env"];
+        tty?: boolean;
+        input?: string | Buffer;
+        captureOutput?: boolean;
+        activityTimeoutMs?: number;
+        onStdout?(chunk: string): void;
+        onStderr?(chunk: string): void;
+    };
+    shellSpec?: RunSpec;
+}
+export interface ExecutionState {
+    templates: {
+        get(backend: "docker" | "e2b", hash: string): Promise<TemplateEntry | null>;
+        put(backend: "docker" | "e2b", entry: TemplateEntry): Promise<void>;
+    };
+}
+export interface TemplateEntry {
+    hash: string;
+    template_id?: string;
+    image?: string;
+    runtime_type: string;
+    dockerfile_path: string;
+    built_at: string;
+}
+export interface UploadResult {
+    files: number;
+    bytes: number;
+    skipped: {
+        path: string;
+        bytes: number;
+        reason: "max_size";
+    }[];
+}
+export interface DownloadResult {
+    files: number;
+    bytes: number;
+    conflicts: {
+        path: string;
+        reason: "local_modified";
+    }[];
+}
+export interface LogChunk {
+    byteOffset: number;
+    data: string;
+}
+export interface AttachedJobContext {
+    jobId: string;
+    tool: string;
+    argv: string[];
+    cwd: string;
+}
+export interface OpenedEnv {
+    readonly id: string;
+    readonly job: JobHandle | null;
+    uploadWorkspace(): Promise<UploadResult>;
+    downloadWorkspace(opts: {
+        conflictPolicy: "refuse" | "overwrite";
+    }): Promise<DownloadResult>;
+    exec(spec: RunSpec): RunHandle;
+    detach(): Promise<JobHandle>;
+    shell(): RunHandle;
+    close(): Promise<void>;
+}
+export interface JobHandle {
+    readonly id: string;
+    readonly envId: string;
+    readonly tool: string;
+    readonly argv: string[];
+    status(): Promise<JobStatus>;
+    stream(opts?: {
+        sinceByte?: number;
+        since?: Date;
+    }): AsyncIterable<LogChunk>;
+    wait(): Promise<{
+        exitCode: number;
+    }>;
+    kill(signal?: NodeJS.Signals): Promise<void>;
+}
+export type Engine = "docker" | "podman";
+export interface DockerMount {
+    source: string;
+    target: string;
+    readonly?: boolean;
+}
+export interface DockerPortMapping {
+    host: number;
+    container: number;
+    protocol?: "tcp" | "udp";
+}
+export interface DockerRunnerOptions {
+    image: string;
+    engine?: Engine;
+    context?: string;
+    mounts?: DockerMount[];
+    ports?: DockerPortMapping[];
+    network?: string;
+    extraArgs?: string[];
+    containerName?: string;
+}
+export interface DockerRunArgs {
+    engine: Engine;
+    context: string | null;
+    image: string;
+    command: string;
+    args: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    mounts: DockerMount[];
+    ports: DockerPortMapping[];
+    network?: string;
+    containerName: string;
+    detached: boolean;
+    interactive: boolean;
+    tty: boolean;
+    rm: boolean;
+    extraArgs: string[];
+}
+export interface MockRunBehavior {
+    pid?: number;
+    exitCode: number;
+    exitAfterMs?: number;
+    stdout?: string[];
+    stderr?: string[];
+    stdoutInterval?: number;
+}

package/node_modules/@poe-code/process-runner/dist/types.js

@@ -0,0 +1 @@
+export {};

package/node_modules/@poe-code/process-runner/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@poe-code/process-runner",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "cd ../.. && vitest run --config vitest.config.ts packages/process-runner/src/**/*.test.ts",
+    "test:unit": "cd ../.. && vitest run --config vitest.config.ts packages/process-runner/src/**/*.test.ts",
+    "lint": "cd ../.. && eslint packages/process-runner/src --ext ts && tsc -p packages/process-runner/tsconfig.json --noEmit"
+  },
+  "files": [
+    "dist"
+  ]
+}

package/node_modules/@poe-code/task-list/README.md

@@ -4,10 +4,13 @@ Multi-list task manager with pluggable storage backends.
 
 ## Backends
 
-`@poe-code/task-list` exposes one API over two backends:
+`@poe-code/task-list` exposes one API over these backends:
 
-- `markdown-dir`: one Markdown file per task, organized into subdirectories per list
-- `yaml-file`: one YAML document with a top-level `lists:` mapping
+| Backend | Storage |
+| --- | --- |
+| `markdown-dir` | One Markdown file per task, organized into subdirectories per list. |
+| `yaml-file` | One YAML document with a top-level `lists:` mapping. |
+| `gh-issues` | GitHub Issues in one repository, ordered and state-tracked through a GitHub Project v2 Status field. |
 
 The task lifecycle is `draft -> planned -> in-progress -> done -> archived`. `archived` is terminal.
 
@@ -47,7 +50,7 @@ Pass a custom machine with `openTaskList({ stateMachine })`. If omitted, the pac
 
 | Option | Type | Default | Behavior |
 | --- | --- | --- | --- |
-| `type` | `"markdown-dir" \| "yaml-file"` | required | Selects the backend implementation. |
+| `type` | `"markdown-dir" \| "yaml-file" \| "gh-issues"` | required | Selects the backend implementation. |
 | `path` | `string` | required | Root directory for `markdown-dir` or YAML file path for `yaml-file`. |
 | `defaults` | `TaskDefaults` | `{ metadata: {} }` | Seeds omitted metadata on new tasks only. New tasks always start at the configured state machine's initial state. |
 | `create` | `boolean` | `false` | Creates missing storage for the selected backend when enabled. |
@@ -58,7 +61,9 @@ Pass a custom machine with `openTaskList({ stateMachine })`. If omitted, the pac
 
 ## Env vars
 
-None.
+| Env var | Behavior |
+| --- | --- |
+| `GH_HOST` | Defers to gh CLI's host configuration; set GH_HOST to override. |
 
 ## Usage
 
@@ -105,6 +110,36 @@ await planning.fire("review-release", "plan");
 await planning.fire("review-release", "start");
 ```
 
+### `gh-issues`
+
+```ts
+import { openTaskList } from "@poe-code/task-list";
+
+const taskList = await openTaskList({
+  type: "gh-issues",
+  repo: "octo-org/octo-repo",
+  project: {
+    owner: "octo-org",
+    number: 7
+  }
+});
+
+const project = taskList.list("octo-org/7");
+
+await taskList.lists(); // ["octo-org/7"]
+
+const created = await project.create({
+  id: "local-id-is-ignored",
+  name: "Review release checklist"
+});
+
+await project.fire(created.id, "In Progress");
+await project.move(created.id, { position: "top" });
+await project.move(created.id, { after: "42" });
+```
+
+`gh-issues` exposes one list named `${project.owner}/${project.number}`. `create()` ignores `TaskCreate.id` because GitHub assigns issue numbers. `fire(state)` writes the Project v2 `Status` field to the matching single-select option. `move()` reorders project items.
+
 ## Notes
 
 The package never overwrites existing task files or store files. `defaults.metadata` is applied only when creating new tasks and does not retroactively update existing tasks.
@@ -112,3 +147,12 @@ The package never overwrites existing task files or store files. `defaults.metad
 Task state changes are event-driven: use `fire(id, event)` to move between states, `canFire(id, event)` to check whether an event is currently legal, and `events(id)` to list the currently legal event names. There is no `transition()` API.
 
 `create()` always starts new tasks at `stateMachine.initial`. `update()` cannot change `state`; use `fire()` instead.
+
+### `gh-issues` limitations
+
+- The state machine is fetched at open and frozen for the session; re-open to refresh project Status options.
+- `archived` is not supported and returns an empty result.
+- `update()` does not write labels, assignees, or milestone in v1.
+- `moveBetweenLists()` is unsupported on `gh-issues`.
+- `id` on `TaskCreate` is ignored on this backend.
+- `gh auth token` must be available, or pass `auth: { token }`.

package/node_modules/@poe-code/task-list/dist/backends/gh-issues-client.d.ts

@@ -0,0 +1,19 @@
+import { type Runner } from "@poe-code/process-runner";
+export interface GhClientOptions {
+    token: string;
+    endpoint?: string;
+    fetch?: typeof fetch;
+}
+export interface GhClient {
+    graphql<T>(query: string, variables: Record<string, unknown>): Promise<T>;
+}
+export declare function createGhClient(options: GhClientOptions): GhClient;
+export interface ResolveAuthOptions {
+    explicitToken?: string;
+    runner?: Runner;
+}
+export declare function resolveAuth(options: ResolveAuthOptions): Promise<string>;
+export interface ResolveEndpointOptions {
+    env?: Record<string, string | undefined>;
+}
+export declare function resolveEndpoint(options?: ResolveEndpointOptions): string;

package/node_modules/@poe-code/task-list/dist/backends/gh-issues-client.js

@@ -0,0 +1,62 @@
+import { text } from "node:stream/consumers";
+import { createHostRunner } from "@poe-code/process-runner";
+const DEFAULT_ENDPOINT = "https://api.github.com/graphql";
+const USER_AGENT = "poe-code-task-list/0.0.1";
+const AUTH_ERROR = "gh auth token failed; install gh, run 'gh auth login', or pass auth: { token }";
+export function createGhClient(options) {
+    const fetchImpl = options.fetch ?? fetch;
+    const endpoint = options.endpoint || DEFAULT_ENDPOINT;
+    return {
+        async graphql(query, variables) {
+            const response = await fetchImpl(endpoint, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${options.token}`,
+                    "Content-Type": "application/json",
+                    "User-Agent": USER_AGENT
+                },
+                body: JSON.stringify({ query, variables })
+            });
+            const body = await response.text();
+            if (response.status !== 200) {
+                throw new Error(`GitHub GraphQL request failed with status ${response.status}: ${body}`);
+            }
+            const parsed = JSON.parse(body);
+            const firstError = parsed.errors?.[0];
+            if (firstError !== undefined) {
+                throw new Error(firstError.message ?? "GitHub GraphQL request failed");
+            }
+            return parsed.data;
+        }
+    };
+}
+export async function resolveAuth(options) {
+    if (options.explicitToken !== undefined) {
+        return options.explicitToken;
+    }
+    const runner = options.runner ?? createHostRunner();
+    const handle = runner.exec({
+        command: "gh",
+        args: ["auth", "token"],
+        stdout: "pipe",
+        stderr: "pipe"
+    });
+    const [stdout, , result] = await Promise.all([
+        handle.stdout === null ? Promise.resolve("") : text(handle.stdout),
+        handle.stderr === null ? Promise.resolve("") : text(handle.stderr),
+        handle.result
+    ]);
+    const token = stdout.trim();
+    if (result.exitCode !== 0 || token.length === 0) {
+        throw new Error(AUTH_ERROR);
+    }
+    return token;
+}
+export function resolveEndpoint(options = {}) {
+    const env = options.env ?? process.env;
+    const host = env.GH_HOST;
+    if (host !== undefined && host !== "" && host !== "github.com") {
+        return `https://${host}/api/graphql`;
+    }
+    return DEFAULT_ENDPOINT;
+}

package/node_modules/@poe-code/task-list/dist/backends/gh-issues.d.ts

@@ -0,0 +1,13 @@
+import type { TaskDefaults, TaskList } from "../types.js";
+export interface GhIssuesBackendDeps {
+    repo: string;
+    project: {
+        owner: string;
+        number: number;
+    };
+    defaults: Required<TaskDefaults>;
+    token: string;
+    endpoint: string;
+    fetch?: typeof fetch;
+}
+export declare function ghIssuesBackend(deps: GhIssuesBackendDeps): Promise<TaskList>;