spawnfile 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Noopolis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,464 @@
+# Spawnfile
+
+> *Canonical source for autonomous agents. Write once. Compile to any runtime.*
+
+---
+
+## What Spawnfile Is
+
+Spawnfile is a spec and source format for declaring autonomous agents and teams independently of the runtime that will host them.
+
+A Spawnfile source project is a directory you own and version. It describes the portable parts of an agent: markdown identity docs, skills, MCP connections, runtime binding, execution intent, and team structure.
+
+`spawnfile compile` lowers that canonical source into runtime-specific config and workspace files. It is not a runtime-to-runtime translator. The compiler starts from the canonical source and emits each declared adapter's output.
+It also emits runnable container artifacts for the compiled output: `Dockerfile`, `entrypoint.sh`, `.env.example`, and a prebuilt `container/rootfs/` tree.
+`spawnfile build` turns that output into a Docker image using the pinned compiled runtime artifacts from `runtimes.yaml`, and `spawnfile run` is the auth-aware wrapper over `docker run`.
+
+---
+
+## V0.1 Scope
+
+Spawnfile v0.1 targets **autonomous agent runtimes** — systems that host agents as long-lived services with markdown workspace identity. It focuses on the portable surface shared across compatible runtimes:
+
+- identity and personality docs (SOUL.md, IDENTITY.md, AGENTS.md)
+- memory and heartbeat intent docs
+- skills with SKILL.md
+- MCP declarations
+- runtime binding
+- execution intent (model, workspace, sandbox)
+- team structure (members, hierarchy, shared surfaces)
+- agent-level Discord, Telegram, WhatsApp, and Slack surfaces
+
+v0.1 does not try to standardize every runtime-native feature. Beyond the initial Discord, Telegram, WhatsApp, and Slack surfaces, communication surfaces, memory engines, task schedulers, UI surfaces, and other runtime-specific features stay adapter-defined for now.
+
+---
+
+## Companion Docs
+
+- `specs/INDEX.md` - map of all specs with status and relationships
+- `specs/SPEC.md` - canonical Spawnfile source spec
+- `specs/COMPILER.md` - v0.1 compiler architecture, graph resolution, and adapter contract
+- `specs/CONTAINERS.md` - container compilation spec
+- `specs/RUNTIMES.md` - runtime registry, version pinning, and adapter lifecycle
+- `specs/research/` - per-runtime research notes and adapter strategies
+- `fixtures/` - canonical v0.1 source projects for compiler validation
+
+---
+
+## Technology
+
+Spawnfile v0.1 is implemented as a Node.js CLI in TypeScript.
+
+- runtime: Node.js 22+
+- CLI: `commander`
+- manifest parsing: `yaml` + `zod`
+- tests: `vitest`
+
+That gives us fast iteration, a conventional `bin`-based CLI, and a clean path to future install surfaces such as npm or a shell bootstrapper.
+
+---
+
+## Install
+
+From a repository checkout:
+
+```bash
+nvm use
+npm install
+npm run build
+npm link
+```
+
+Or use the bootstrap script:
+
+```bash
+./scripts/install.sh
+```
+
+Then:
+
+```bash
+spawnfile --help
+```
+
+To clone the target runtimes and generate reference blueprints:
+
+```bash
+npm run runtimes:sync
+```
+
+This clones each runtime at the version pinned in `runtimes.yaml` and generates blueprints showing the expected config and workspace layout. See `blueprints/` for the output.
+
+These clones are for local research, blueprint generation, and adapter work. `spawnfile compile` itself does not need local runtime clones.
+
+For local development without linking globally:
+
+```bash
+npm run dev -- validate fixtures/single-agent
+```
+
+---
+
+## Why
+
+The autonomous agent runtimes are different, but they already share a meaningful core: markdown workspace identity, skill folders, MCP, model selection, and workspace isolation. Today that core is re-authored by hand for each runtime. Spawnfile makes it canonical.
+
+---
+
+## How It Works
+
+You write a source project once. Then you compile it:
+
+```bash
+spawnfile init
+spawnfile init --runtime tinyclaw
+spawnfile validate
+spawnfile compile
+spawnfile auth sync --profile dev --env-file .env
+spawnfile build
+spawnfile run --auth-profile dev
+```
+
+For a single agent, the compiler uses that manifest's declared runtime. For a team, it walks the member graph and compiles each member using that member's declared runtime.
+
+Each adapter maps the canonical project into runtime-native forms. If a runtime cannot preserve a declaration, the compiler reports `supported`, `degraded`, or `unsupported` according to the project's compile policy.
+
+Each compile also produces a machine-readable report describing the resolved graph, chosen runtimes, output locations, and capability outcomes.
+
+The portable model stays intentionally small:
+
+- `runtime` names the host runtime and may carry runtime-specific options
+- `execution` carries portable intent like model, workspace, and sandbox
+- `agent` may hold internal `subagents`
+- `team` is for first-class agents that coordinate as a group
+
+---
+
+## Project Structure
+
+A source project has a `kind` - either `agent` or `team`.
+
+### Agent
+
+```text
+my-agent/
+├── Spawnfile
+├── IDENTITY.md
+├── SOUL.md
+├── AGENTS.md
+├── MEMORY.md
+├── HEARTBEAT.md
+├── subagents/
+│   └── researcher/
+│       └── Spawnfile
+└── skills/
+    ├── web_search/
+    │   └── SKILL.md
+    └── memory_store/
+        └── SKILL.md
+```
+
+Not every file is required. Spawnfile names portable document roles; adapters decide how to lower them into target-native surfaces.
+
+### Team
+
+```text
+my-team/
+├── Spawnfile
+├── TEAM.md
+├── shared/
+│   └── skills/
+│       └── web_search/
+│           └── SKILL.md
+└── agents/
+    ├── orchestrator/
+    │   ├── Spawnfile
+    │   └── AGENTS.md
+    ├── researcher/
+    │   ├── Spawnfile
+    │   └── SOUL.md
+    └── writer/
+        ├── Spawnfile
+        └── SOUL.md
+```
+
+Teams can reference agents or other teams. Team structure (hierarchy, leadership) is part of the canonical model, but preservation is target-dependent and explicitly reported by the compiler.
+Team members may be on the same runtime or on different runtimes depending on what each member declares.
+
+An `agent` may also declare internal `subagents`. Those are not the same as a `team`: they are helper agents owned by a parent agent and lowered according to that runtime's own delegation or subagent model.
+
+---
+
+## Policy
+
+Not every target supports every declared capability. Spawnfile makes that explicit:
+
+```yaml
+policy:
+  mode: strict
+  on_degrade: error
+```
+
+The compiler reports one of three outcomes per declared capability: `supported`, `degraded`, or `unsupported`.
+
+---
+
+## The CLI
+
+```bash
+spawnfile init
+spawnfile init --runtime tinyclaw
+spawnfile init --team
+spawnfile add agent writer
+spawnfile add subagent critic
+spawnfile add team platform
+spawnfile validate
+spawnfile compile
+spawnfile auth
+spawnfile build
+spawnfile run
+```
+
+For example:
+
+```bash
+spawnfile init --runtime picoclaw ./agents/researcher
+spawnfile add agent writer ./my-team --runtime tinyclaw
+spawnfile add subagent critic ./my-agent
+spawnfile add team platform ./my-team
+spawnfile validate fixtures/single-agent
+spawnfile compile fixtures/single-agent --out ./bundle/example
+spawnfile auth sync fixtures/single-agent --profile dev --env-file ./.env
+spawnfile build fixtures/single-agent --out ./bundle/example --tag example-agent
+spawnfile run fixtures/single-agent --tag example-agent --auth-profile dev
+```
+
+Without `--out`, the compiler writes generated artifacts under `.spawn/`. `spawnfile init` also ensures `.spawn/` is ignored in the project `.gitignore`.
+
+The compiler emits runtime-specific artifacts under `.spawn/runtimes/...` by default and writes a machine-readable `spawnfile-report.json`.
+
+`spawnfile init` defaults agent scaffolds to `openclaw`. Use `spawnfile init --runtime <name>` to scaffold an agent for a different bundled runtime. `spawnfile init --team` stays runtime-neutral.
+
+`spawnfile add` grows an existing manifest graph in place. The target `[path]` is optional and defaults to the current directory. It must point to the parent project directory (or its `Spawnfile`):
+
+- `spawnfile add agent <id> [path]` adds `agents/<id>/` under a team
+  If `--runtime` is omitted, it uses the same default agent runtime as `spawnfile init`.
+- `spawnfile add subagent <id> [path]` adds `subagents/<id>/` under an agent
+- `spawnfile add team <id> [path]` adds `teams/<id>/` under a team
+
+The CLI rejects invalid parent kinds: `add agent` and `add team` only work on team projects, and `add subagent` only works on agent projects.
+
+`spawnfile model` edits model intent in place and rewrites touched manifests to the canonical inline shape:
+
+- `spawnfile model set <provider> <name> [path]` sets the primary model
+- `spawnfile model add-fallback <provider> <name> [path]` appends a fallback model
+- `spawnfile model clear-fallbacks [path]` removes fallback models
+- if `[path]` points to a team project, `--recursive` is required and only descendant agent manifests are updated; the team manifest itself is left unchanged
+- the first positional argument is always the model provider, not the auth method
+
+Team manifests should not declare `execution`. Model, sandbox, and workspace intent belong to agent manifests, not teams.
+
+Agent manifests may declare portable communication surfaces under `surfaces`. The first standardized surfaces are Discord, Telegram, WhatsApp, and Slack:
+
+```yaml
+surfaces:
+  discord:
+    access:
+      users:
+        - "987654321098765432"
+    bot_token_secret: DISCORD_BOT_TOKEN
+  telegram:
+    access:
+      users:
+        - "123456789"
+      chats:
+        - "-1001234567890"
+    bot_token_secret: TELEGRAM_BOT_TOKEN
+  whatsapp:
+    access:
+      users:
+        - "15551234567"
+      groups:
+        - "120363400000000000@g.us"
+  slack:
+    access:
+      users:
+        - "U1234567890"
+      channels:
+        - "C1234567890"
+    bot_token_secret: SLACK_BOT_TOKEN
+    app_token_secret: SLACK_APP_TOKEN
+```
+
+Discord access may declare:
+
+- `mode: pairing | allowlist | open`
+- `users`
+- `guilds`
+- `channels`
+
+Telegram access may declare:
+
+- `mode: pairing | allowlist | open`
+- `users`
+- `chats`
+
+WhatsApp access may declare:
+
+- `mode: pairing | allowlist | open`
+- `users`
+- `groups`
+
+Slack access may declare:
+
+- `mode: pairing | allowlist | open`
+- `users`
+- `channels`
+
+If `mode` is omitted and any allowlist fields are present, Spawnfile infers `allowlist`.
+If you want portable runtime behavior, set `access.mode` explicitly. Leaving `access` unset delegates to runtime defaults, which are not identical across runtimes.
+If `bot_token_secret` is omitted, Spawnfile defaults to `DISCORD_BOT_TOKEN` for Discord, `TELEGRAM_BOT_TOKEN` for Telegram, and `SLACK_BOT_TOKEN` for Slack. If `app_token_secret` is omitted on Slack, Spawnfile defaults to `SLACK_APP_TOKEN`.
+WhatsApp has no portable token-secret field in v0.1; session or QR-style auth remains runtime-defined.
+`spawnfile auth sync ... --env-file .env` will collect that env name into the selected auth profile, and `spawnfile run --auth-profile ...` will validate it before container startup.
+
+Runtime support is narrower than the portable schema:
+
+- `openclaw` supports `pairing`, `allowlist`, and `open` for Discord, Telegram, WhatsApp, and Slack
+- `picoclaw` supports `open` and user allowlists for Discord, Telegram, WhatsApp, and Slack
+- `tinyclaw` supports `pairing` only for Discord, Telegram, and WhatsApp, and does not support Slack in Spawnfile v0.1
+
+Practical notes from the current live smoke matrix:
+
+- Discord was verified end to end on OpenClaw and PicoClaw, and as a paired DM surface on TinyClaw
+- Telegram was verified end to end on all three runtimes
+- `tinyclaw` required first-contact pairing on Telegram
+- `openclaw` and `picoclaw` both worked on Telegram with `access.mode: open`
+- WhatsApp was verified end to end on OpenClaw
+- `picoclaw` WhatsApp remains blocked in the pinned artifact because `whatsapp_native` is not compiled into the shipped binary
+- `tinyclaw` WhatsApp remains blocked in the shipped container because the upstream client needs a browser runtime
+- Slack was verified end to end on OpenClaw
+- Slack was verified end to end on PicoClaw
+- `picoclaw` replies to channel messages in a Slack thread; direct messages reply inline
+
+Useful options:
+
+- `--auth <api_key|claude-code|codex|none>` sets the auth method on the edited model target
+- `--key <ENV_NAME>` sets the env var name used by `api_key` auth for custom/local models
+- `--compat <openai|anthropic>` and `--base-url <url>` configure local/custom endpoint targets
+- `--recursive` updates the target project and every descendant manifest in the graph
+
+Examples:
+
+```bash
+spawnfile model set anthropic claude-opus-4-6 --auth claude-code
+spawnfile model set openai gpt-5.4 --auth codex
+spawnfile model set local qwen2.5:14b --auth none --compat openai --base-url http://host.docker.internal:11434/v1
+spawnfile model set anthropic claude-opus-4-6 . --auth claude-code --recursive
+```
+
+`spawnfile compile` also emits under the output root:
+
+- final container filesystem output under `.spawn/container/rootfs/...` by default
+- `Dockerfile`, `entrypoint.sh`, `.env.example`
+
+`spawnfile build` is the happy path for compile + Docker image build. It compiles the project, then runs `docker build` against the emitted output directory. The generated Dockerfile installs the pinned compiled runtime artifacts for the resolved runtimes; it does not rebuild runtime sources during image build.
+
+`spawnfile build` remains secrets-free by default. Runtime and model auth should be prepared locally, then applied at `spawnfile run` time.
+
+Model auth can be imported into a local Spawnfile auth profile:
+
+```bash
+spawnfile auth sync fixtures/single-agent --profile dev --env-file ./.env
+spawnfile auth show --profile dev
+```
+
+Projects declare model auth on each model entry in the Spawnfile, for example:
+
+```yaml
+execution:
+  model:
+    primary:
+      provider: anthropic
+      name: claude-opus-4-6
+      auth:
+        method: claude-code
+```
+
+For local and custom endpoints, the model entry can also declare `endpoint`:
+
+```yaml
+execution:
+  model:
+    primary:
+      provider: local
+      name: qwen2.5:14b
+      auth:
+        method: none
+      endpoint:
+        compatibility: openai
+        base_url: http://host.docker.internal:11434/v1
+```
+
+`spawnfile auth sync` reads that declared intent and imports the matching local auth material into the selected profile. The lower-level `spawnfile auth import env`, `spawnfile auth import claude-code`, and `spawnfile auth import codex` commands remain available for manual profile editing. The older top-level `execution.model.auth` form is still accepted for compatibility, but inline per-model auth is the canonical shape.
+
+`env` auth is the primary path for provider API keys. `claude-code` and `codex` imports mount existing local CLI credential stores into runtime homes at `spawnfile run` time.
+
+Then run the built image with that profile:
+
+```bash
+spawnfile run fixtures/single-agent --tag example-agent --auth-profile dev
+```
+
+Manual Docker remains valid against the compile output:
+
+```bash
+spawnfile build fixtures/single-agent --out ./bundle/example --tag example-agent
+cp ./bundle/example/.env.example ./bundle/example/.env
+docker run --env-file ./bundle/example/.env -p 18789:18789 example-agent
+```
+
+Equivalent manual flow:
+
+```bash
+spawnfile compile fixtures/single-agent --out ./bundle/example
+cd ./bundle/example
+docker build -t example-agent .
+docker run --env-file .env -p 18789:18789 example-agent
+```
+
+## Docker E2E
+
+The repo also includes an opt-in Docker auth E2E harness.
+It builds compiled images, starts them with a local Spawnfile auth profile, waits for runtime readiness, sends real prompts, and fails unless the expected sentinel reply comes back.
+
+Examples:
+
+```bash
+npm run test:e2e:docker-auth -- --scenario openclaw-codex
+npm run test:e2e:docker-auth -- --scenario team-multi-runtime --env-file ../headhunter/.env
+```
+
+This is intentionally separate from `npm test`.
+It requires Docker, network access, and real model credentials.
+
+---
+
+## The Builder
+
+**spawnfile.ai** is a web-based authoring surface for the canonical format. It walks through docs, skills, MCP, runtime binding, execution intent, and team composition, then produces a source project you own and can edit by hand.
+
+---
+
+## The Name
+
+**Spawn** - in computing, you spawn a process. In games, you spawn a character. In biology, you spawn life. Deliberate creation. Independent existence from that point forward.
+
+**File** - the atomic unit of software. Something you can read, version, fork, check into git, and own completely. It anchors a project - a directory, a complete picture of what something is.
+
+Together: *a canonical source project that spawns an agent and can be compiled into the runtimes that can host it.*
+
+---
+
+*One source format. Many runtimes. Manifest-driven compilation.*
+
+**spawnfile.ai** · **github.com/noopolis/spawnfile**

package/dist/.env.example

@@ -0,0 +1,5 @@
+# Generated by spawnfile compile
+
+# Required
+# Model provider auth for ANTHROPIC_API_KEY
+ANTHROPIC_API_KEY=

package/dist/Dockerfile

@@ -0,0 +1,21 @@
+FROM debian:bookworm-slim
+USER root
+
+WORKDIR /opt/spawnfile
+RUN apt-get update && apt-get install -y --no-install-recommends bash ca-certificates curl nodejs npm tar && rm -rf /var/lib/apt/lists/*
+
+RUN npm install -g --omit=dev --no-fund --no-audit @anthropic-ai/claude-code @openai/codex
+
+RUN mkdir -p /opt/spawnfile/runtime-installs/picoclaw/bin
+RUN arch="$(dpkg --print-architecture)" && case "$arch" in amd64) asset="picoclaw_Linux_x86_64.tar.gz" ;; arm64) asset="picoclaw_Linux_arm64.tar.gz" ;; *) echo "Unsupported PicoClaw release architecture: $arch" >&2; exit 1 ;; esac && url="https://github.com/sipeed/picoclaw/releases/download/v0.2.3/$asset" && curl -fsSL -o /tmp/picoclaw.tar.gz "$url" && rm -rf /tmp/picoclaw-extract && mkdir -p /tmp/picoclaw-extract && tar -xzf /tmp/picoclaw.tar.gz -C /tmp/picoclaw-extract && binary_path="$(find /tmp/picoclaw-extract -type f -name "picoclaw" | head -n 1)" && [ -n "$binary_path" ] && install -m 0755 "$binary_path" /opt/spawnfile/runtime-installs/picoclaw/bin/picoclaw && ln -sf /opt/spawnfile/runtime-installs/picoclaw/bin/picoclaw /usr/local/bin/picoclaw && rm -rf /tmp/picoclaw.tar.gz /tmp/picoclaw-extract
+
+RUN if ! id -u spawnfile >/dev/null 2>&1; then useradd --create-home --home-dir /home/spawnfile --shell /bin/bash spawnfile; fi
+
+COPY container/rootfs/ /
+COPY .env.example /opt/spawnfile/.env.example
+COPY entrypoint.sh /opt/spawnfile/entrypoint.sh
+RUN chmod +x /opt/spawnfile/entrypoint.sh
+RUN mkdir -p /var/lib/spawnfile && chown -R spawnfile:spawnfile /var/lib/spawnfile /opt/spawnfile
+EXPOSE 18790
+USER spawnfile
+ENTRYPOINT ["/opt/spawnfile/entrypoint.sh"]

package/dist/auth/importers.d.ts

@@ -0,0 +1,8 @@
+interface ClaudeCodeImportOptions {
+    readKeychainCredentials?: () => Promise<string | null>;
+}
+export declare const parseEnvFile: (content: string) => Record<string, string>;
+export declare const importEnvFile: (profileName: string, envFilePath: string) => Promise<import("./types.js").ResolvedAuthProfile>;
+export declare const importCodexAuth: (profileName: string, sourceDirectory?: string) => Promise<import("./types.js").ResolvedAuthProfile>;
+export declare const importClaudeCodeAuth: (profileName: string, sourceDirectory?: string, options?: ClaudeCodeImportOptions) => Promise<import("./types.js").ResolvedAuthProfile>;
+export {};

package/dist/auth/importers.js

@@ -0,0 +1,93 @@
+import path from "node:path";
+import os from "node:os";
+import { ensureDirectory, fileExists, readUtf8File, writeUtf8File } from "../filesystem/index.js";
+import { SpawnfileError } from "../shared/index.js";
+import { registerImportedAuth, setAuthProfileEnv } from "./profileStore.js";
+const ENV_LINE_PATTERN = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/;
+const CLAUDE_CODE_KEYCHAIN_SERVICE = "Claude Code-credentials";
+const stripWrappedQuotes = (value) => {
+    const trimmed = value.trim();
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+        (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+};
+export const parseEnvFile = (content) => {
+    const entries = {};
+    for (const rawLine of content.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (line.length === 0 || line.startsWith("#")) {
+            continue;
+        }
+        const match = rawLine.match(ENV_LINE_PATTERN);
+        if (!match) {
+            throw new SpawnfileError("validation_error", `Invalid env line: ${rawLine}`);
+        }
+        entries[match[1]] = stripWrappedQuotes(match[2] ?? "");
+    }
+    return entries;
+};
+export const importEnvFile = async (profileName, envFilePath) => {
+    if (!(await fileExists(envFilePath))) {
+        throw new SpawnfileError("validation_error", `Env file does not exist: ${envFilePath}`);
+    }
+    return setAuthProfileEnv(profileName, parseEnvFile(await readUtf8File(envFilePath)));
+};
+const resolveHomeRelativePath = (defaultRelativePath, inputPath) => {
+    if (inputPath) {
+        return path.resolve(inputPath);
+    }
+    return path.join(os.homedir(), defaultRelativePath);
+};
+const resolveCodexSourceDirectory = (sourceDirectory) => path.resolve(sourceDirectory ?? process.env.CODEX_HOME ?? resolveHomeRelativePath(".codex"));
+const resolveClaudeSourceDirectory = (sourceDirectory) => resolveHomeRelativePath(".claude", sourceDirectory);
+const readClaudeCodeKeychainCredentials = async () => {
+    try {
+        const { execFile } = await import("node:child_process");
+        const { promisify } = await import("node:util");
+        const execFileAsync = promisify(execFile);
+        const { stdout } = await execFileAsync("security", [
+            "find-generic-password",
+            "-s",
+            CLAUDE_CODE_KEYCHAIN_SERVICE,
+            "-w"
+        ]);
+        const content = stdout.trim();
+        return content.length > 0 ? content : null;
+    }
+    catch {
+        return null;
+    }
+};
+export const importCodexAuth = async (profileName, sourceDirectory) => {
+    const resolvedSource = resolveCodexSourceDirectory(sourceDirectory);
+    const authFilePath = path.join(resolvedSource, "auth.json");
+    if (!(await fileExists(authFilePath))) {
+        throw new SpawnfileError("validation_error", `Codex auth file does not exist: ${authFilePath}`);
+    }
+    const { directory, profile } = await registerImportedAuth(profileName, "codex");
+    await writeUtf8File(path.join(directory, "auth.json"), await readUtf8File(authFilePath));
+    return profile;
+};
+export const importClaudeCodeAuth = async (profileName, sourceDirectory, options = {}) => {
+    const resolvedSource = resolveClaudeSourceDirectory(sourceDirectory);
+    const credentialsPath = path.join(resolvedSource, ".credentials.json");
+    let credentialsContent = null;
+    if (await fileExists(credentialsPath)) {
+        credentialsContent = await readUtf8File(credentialsPath);
+    }
+    if (!credentialsContent && !sourceDirectory) {
+        const keychainCredentials = await (options.readKeychainCredentials ?? readClaudeCodeKeychainCredentials)();
+        if (keychainCredentials) {
+            credentialsContent = keychainCredentials;
+        }
+    }
+    if (!credentialsContent) {
+        throw new SpawnfileError("validation_error", `Claude Code credentials file does not exist: ${credentialsPath} and macOS Keychain service ${CLAUDE_CODE_KEYCHAIN_SERVICE} was unavailable`);
+    }
+    const { directory, profile } = await registerImportedAuth(profileName, "claude-code");
+    await ensureDirectory(directory);
+    await writeUtf8File(path.join(directory, ".credentials.json"), credentialsContent);
+    return profile;
+};

package/dist/auth/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./importers.js";
+export * from "./paths.js";
+export * from "./profileStore.js";
+export * from "./runtimeCredentials.js";
+export * from "./types.js";

package/dist/auth/index.js

@@ -0,0 +1,5 @@
+export * from "./importers.js";
+export * from "./paths.js";
+export * from "./profileStore.js";
+export * from "./runtimeCredentials.js";
+export * from "./types.js";

package/dist/auth/paths.d.ts

@@ -0,0 +1,6 @@
+export declare const resolveSpawnfileHome: () => string;
+export declare const resolveAuthHome: () => string;
+export declare const resolveProfilesRoot: () => string;
+export declare const resolveProfileDirectory: (profileName: string) => string;
+export declare const resolveProfilePath: (profileName: string) => string;
+export declare const resolveImportedAuthDirectory: (profileName: string, kind: "claude-code" | "codex") => string;

package/dist/auth/paths.js

@@ -0,0 +1,18 @@
+import os from "node:os";
+import path from "node:path";
+const DEFAULT_SPAWNFILE_HOME = "~/.spawnfile";
+const expandHomePath = (inputPath) => {
+    if (inputPath === "~") {
+        return os.homedir();
+    }
+    if (inputPath.startsWith("~/")) {
+        return path.join(os.homedir(), inputPath.slice(2));
+    }
+    return inputPath;
+};
+export const resolveSpawnfileHome = () => path.resolve(expandHomePath(process.env.SPAWNFILE_HOME ?? DEFAULT_SPAWNFILE_HOME));
+export const resolveAuthHome = () => path.join(resolveSpawnfileHome(), "auth");
+export const resolveProfilesRoot = () => path.join(resolveAuthHome(), "profiles");
+export const resolveProfileDirectory = (profileName) => path.join(resolveProfilesRoot(), profileName);
+export const resolveProfilePath = (profileName) => path.join(resolveProfileDirectory(profileName), "profile.json");
+export const resolveImportedAuthDirectory = (profileName, kind) => path.join(resolveProfileDirectory(profileName), "imports", kind);

package/dist/auth/profileStore.d.ts

@@ -0,0 +1,10 @@
+import type { AuthProfile, ImportedAuthKind, ResolvedAuthProfile } from "./types.js";
+export declare const createResolvedAuthProfile: (profileName: string, profile: AuthProfile) => ResolvedAuthProfile;
+export declare const loadAuthProfile: (profileName: string) => Promise<ResolvedAuthProfile | null>;
+export declare const requireAuthProfile: (profileName: string) => Promise<ResolvedAuthProfile>;
+export declare const ensureAuthProfile: (profileName: string) => Promise<ResolvedAuthProfile>;
+export declare const setAuthProfileEnv: (profileName: string, env: Record<string, string>) => Promise<ResolvedAuthProfile>;
+export declare const registerImportedAuth: (profileName: string, kind: ImportedAuthKind) => Promise<{
+    directory: string;
+    profile: ResolvedAuthProfile;
+}>;