copillm 0.1.0

package/dist/agentconfig/schema.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+/**
+ * Schema for `~/.copillm/agent.toml` (global) and `<cwd>/.copillm/agent.toml`
+ * (project overlay). See plans/unified-booping-mango.md for design rationale.
+ *
+ * Sections under `[defaults.*]` apply to every profile; profiles override by
+ * deep-merge. v1 only wires `instructions` and `mcp` into fan-out — the other
+ * sections (`skills`, `agents`, `hooks`, `permissions`) are reserved-but-
+ * permissive so users can start populating them without future TOML breaking.
+ */
+export const UNSET_SENTINEL = "@unset";
+const StringRecord = z.record(z.string());
+const McpStdioSchema = z
+    .object({
+    transport: z.literal("stdio"),
+    command: z.string().min(1),
+    args: z.array(z.string()).optional(),
+    env: StringRecord.optional(),
+    cwd: z.string().optional(),
+    scope: z.enum(["project", "user"]).optional()
+})
+    .strict();
+const McpHttpSchema = z
+    .object({
+    transport: z.enum(["http", "sse"]),
+    url: z.string().url(),
+    headers: StringRecord.optional(),
+    scope: z.enum(["project", "user"]).optional()
+})
+    .strict();
+const McpInheritUnset = z
+    .object({
+    inherit: z.literal(UNSET_SENTINEL)
+})
+    .strict();
+export const McpServerSchema = z.union([McpStdioSchema, McpHttpSchema, McpInheritUnset]);
+const InstructionsSchema = z
+    .object({
+    body: z.string()
+})
+    .strict();
+const McpSchema = z
+    .object({
+    servers: z.record(McpServerSchema).optional()
+})
+    .strict();
+const PassthroughRecord = z.record(z.unknown());
+const SectionSchema = z
+    .object({
+    instructions: InstructionsSchema.optional(),
+    mcp: McpSchema.optional(),
+    // v1 reserved sections: validated as objects but not interpreted.
+    skills: PassthroughRecord.optional(),
+    agents: PassthroughRecord.optional(),
+    hooks: PassthroughRecord.optional(),
+    permissions: PassthroughRecord.optional()
+})
+    .strict();
+export const AgentTomlSchema = z
+    .object({
+    active_profile: z.string().min(1).optional(),
+    defaults: SectionSchema.optional(),
+    profiles: z.record(SectionSchema).optional()
+})
+    .strict();

package/dist/auth/copilotToken.js

@@ -0,0 +1,122 @@
+import { tokenExchangeUrl } from "../config/upstream.js";
+const DEFAULT_REFRESH_THRESHOLD_SECONDS = 300;
+const MIN_ACCEPTABLE_TTL_SECONDS = 30;
+export class CopilotTokenManagerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CopilotTokenManagerError";
+    }
+}
+export class CopilotTokenExchangeError extends CopilotTokenManagerError {
+    statusCode;
+    responseBodySnippet;
+    constructor(message, statusCode, responseBodySnippet) {
+        super(message);
+        this.statusCode = statusCode;
+        this.responseBodySnippet = responseBodySnippet;
+        this.name = "CopilotTokenExchangeError";
+    }
+}
+export class CopilotTokenPayloadError extends CopilotTokenManagerError {
+    constructor(message) {
+        super(message);
+        this.name = "CopilotTokenPayloadError";
+    }
+}
+export class CopilotTokenExpiredError extends CopilotTokenManagerError {
+    constructor(message) {
+        super(message);
+        this.name = "CopilotTokenExpiredError";
+    }
+}
+export class CopilotTokenManager {
+    githubToken;
+    state = null;
+    refreshInFlight = null;
+    constructor(githubToken) {
+        this.githubToken = githubToken;
+    }
+    get current() {
+        return this.state;
+    }
+    expiresInSeconds(nowUnix = this.nowUnix()) {
+        if (!this.state) {
+            return null;
+        }
+        return Math.max(0, this.state.expiresAtUnix - nowUnix);
+    }
+    shouldRefresh(options) {
+        const threshold = options?.refreshThresholdSeconds ?? DEFAULT_REFRESH_THRESHOLD_SECONDS;
+        const expiresIn = this.expiresInSeconds(options?.nowUnix ?? this.nowUnix());
+        return expiresIn === null || expiresIn <= threshold;
+    }
+    async ensureToken(options) {
+        const normalized = this.normalizeEnsureTokenOptions(options);
+        const needsRefresh = normalized.forceRefresh || this.shouldRefresh({ refreshThresholdSeconds: normalized.refreshThresholdSeconds });
+        if (!needsRefresh) {
+            return this.state.token;
+        }
+        const next = await this.refreshToken();
+        return next.token;
+    }
+    clear() {
+        this.state = null;
+        this.refreshInFlight = null;
+    }
+    async exchange() {
+        const response = await fetch(tokenExchangeUrl(), {
+            method: "GET",
+            headers: {
+                Authorization: `token ${this.githubToken}`,
+                "User-Agent": "copillm/0.1.0",
+                Accept: "application/json"
+            }
+        });
+        if (!response.ok) {
+            const responseBody = await response.text();
+            const snippet = responseBody.slice(0, 256);
+            throw new CopilotTokenExchangeError(`Copilot token exchange failed (${response.status}).`, response.status, snippet);
+        }
+        const payload = (await response.json());
+        if (!payload.token || !payload.expires_at || !Number.isFinite(payload.expires_at)) {
+            throw new CopilotTokenPayloadError("Token exchange response was missing required fields.");
+        }
+        const now = this.nowUnix();
+        const ttl = payload.expires_at - now;
+        if (ttl <= MIN_ACCEPTABLE_TTL_SECONDS) {
+            throw new CopilotTokenExpiredError(`Received near-expired Copilot token (ttl_seconds=${Math.max(0, ttl)}).`);
+        }
+        return {
+            token: payload.token,
+            expiresAtUnix: payload.expires_at
+        };
+    }
+    normalizeEnsureTokenOptions(input) {
+        if (typeof input === "boolean") {
+            return {
+                forceRefresh: input,
+                refreshThresholdSeconds: DEFAULT_REFRESH_THRESHOLD_SECONDS
+            };
+        }
+        return {
+            forceRefresh: input?.forceRefresh ?? false,
+            refreshThresholdSeconds: input?.refreshThresholdSeconds ?? DEFAULT_REFRESH_THRESHOLD_SECONDS
+        };
+    }
+    async refreshToken() {
+        if (!this.refreshInFlight) {
+            this.refreshInFlight = this.exchange()
+                .then((next) => {
+                this.state = next;
+                return next;
+            })
+                .finally(() => {
+                this.refreshInFlight = null;
+            });
+        }
+        return this.refreshInFlight;
+    }
+    nowUnix() {
+        return Math.floor(Date.now() / 1000);
+    }
+}

package/dist/auth/credentials.js

@@ -0,0 +1,221 @@
+import fs from "node:fs";
+import { readFileSync } from "node:fs";
+import { z } from "zod";
+import { ensureAppHome } from "../config/config.js";
+import { credentialsPath, credentialsReadPath } from "../config/home.js";
+import { writeFileSecureAtomic } from "../config/fsSecurity.js";
+const SERVICE = "copillm";
+const ACCOUNT = "github-oauth-token";
+const FileCredentialSchema = z.object({
+    version: z.literal(1),
+    github_token: z.string().min(1),
+    account_type: z.enum(["individual", "business", "enterprise"]),
+    saved_at: z.string().min(1)
+});
+// Module-level in-memory credential. Only populated when SaveMode === "session".
+// Never persisted; cleared on clearStoredCredential() and on process exit.
+let sessionCredential = null;
+function forceSessionBackend() {
+    return process.env.COPILLM_FORCE_SESSION_BACKEND === "1";
+}
+async function tryImportKeytar() {
+    if (forceSessionBackend()) {
+        return null;
+    }
+    try {
+        const mod = await import("keytar");
+        return mod.default;
+    }
+    catch (error) {
+        if (isMissingKeytarError(error)) {
+            return null;
+        }
+        if (error instanceof Error) {
+            throw new Error(`Failed to initialize OS keychain backend: ${error.message}`);
+        }
+        throw new Error("Failed to initialize OS keychain backend: unknown error");
+    }
+}
+async function resolveKeytar() {
+    if (forceSessionBackend()) {
+        return { keytar: null, reason: "forced_session_backend" };
+    }
+    const keytar = await tryImportKeytar();
+    if (keytar) {
+        return { keytar, reason: null };
+    }
+    return { keytar: null, reason: "keytar module is unavailable on this machine" };
+}
+function parseCredentialFile() {
+    const path = credentialsReadPath();
+    const raw = readFileSync(path, "utf8");
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(raw);
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            throw new Error(`Credential file exists but contains invalid JSON at ${path}: ${error.message}`);
+        }
+        throw new Error(`Credential file exists but contains invalid JSON at ${path}.`);
+    }
+    try {
+        const parsed = FileCredentialSchema.parse(parsedJson);
+        return { token: parsed.github_token, accountType: parsed.account_type };
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            throw new Error(`Credential file exists but is invalid at ${path}: ${error.message}`);
+        }
+        throw new Error(`Credential file exists but is invalid at ${path}.`);
+    }
+}
+function writeCredentialFile(token, accountType) {
+    ensureAppHome();
+    const payload = {
+        version: 1,
+        github_token: token,
+        account_type: accountType,
+        saved_at: new Date().toISOString()
+    };
+    writeFileSecureAtomic(credentialsPath(), JSON.stringify(payload, null, 2), 0o600);
+}
+function canUsePlaintextFallback() {
+    if (forceSessionBackend()) {
+        return false;
+    }
+    return process.stdin.isTTY || process.env.COPILLM_ALLOW_PLAINTEXT_CREDENTIALS === "1";
+}
+function isMissingKeytarError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    const message = error.message.toLowerCase();
+    return (message.includes("cannot find package 'keytar'") ||
+        message.includes("cannot find module 'keytar'") ||
+        message.includes("module not found"));
+}
+/**
+ * Returns whether a credential is present and which backend holds it.
+ * Never returns the token itself — callers that need to introspect should use
+ * this helper to avoid accidentally pulling the secret into a code path that
+ * might log or print it.
+ */
+export async function inspectStoredCredential() {
+    if (sessionCredential) {
+        return { stored: true, backend: "session" };
+    }
+    if (fs.existsSync(credentialsReadPath())) {
+        return { stored: true, backend: "file" };
+    }
+    const { keytar } = await resolveKeytar();
+    if (!keytar) {
+        return { stored: false, backend: null };
+    }
+    try {
+        const token = await keytar.getPassword(SERVICE, ACCOUNT);
+        if (token) {
+            return { stored: true, backend: "keytar" };
+        }
+        return { stored: false, backend: null };
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            throw new Error(`Failed to read token from OS keychain: ${error.message}`);
+        }
+        throw new Error("Failed to read token from OS keychain.");
+    }
+}
+export async function loadStoredCredential() {
+    if (sessionCredential) {
+        return { token: sessionCredential.token, accountType: sessionCredential.accountType, source: "session" };
+    }
+    if (fs.existsSync(credentialsReadPath())) {
+        const parsed = parseCredentialFile();
+        return { token: parsed.token, accountType: parsed.accountType, source: "file" };
+    }
+    const { keytar } = await resolveKeytar();
+    if (!keytar) {
+        return null;
+    }
+    let token;
+    try {
+        token = await keytar.getPassword(SERVICE, ACCOUNT);
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            throw new Error(`Failed to read token from OS keychain: ${error.message}`);
+        }
+        throw new Error("Failed to read token from OS keychain.");
+    }
+    if (!token) {
+        return null;
+    }
+    return { token, accountType: "individual", source: "keytar" };
+}
+export async function saveStoredCredential(token, accountType, options = {}) {
+    const mode = options.mode ?? "auto";
+    if (mode === "session") {
+        sessionCredential = { token, accountType };
+        return "session";
+    }
+    if (fs.existsSync(credentialsReadPath())) {
+        parseCredentialFile();
+        writeCredentialFile(token, accountType);
+        return "file";
+    }
+    const { keytar, reason } = await resolveKeytar();
+    if (keytar) {
+        try {
+            await keytar.setPassword(SERVICE, ACCOUNT, token);
+            return "keytar";
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Failed to write token to OS keychain: ${error.message}`);
+            }
+            throw new Error("Failed to write token to OS keychain.");
+        }
+    }
+    if (!canUsePlaintextFallback()) {
+        throw new Error(`OS keychain backend unavailable (${reason ?? "unknown reason"}). Plaintext fallback is disabled in non-interactive mode; set COPILLM_ALLOW_PLAINTEXT_CREDENTIALS=1 to allow it.`);
+    }
+    writeCredentialFile(token, accountType);
+    return "file";
+}
+export async function clearStoredCredential() {
+    // Always clear in-memory session token first; it shadows other backends.
+    const hadSession = sessionCredential !== null;
+    sessionCredential = null;
+    const readablePath = credentialsReadPath();
+    const canonicalPath = credentialsPath();
+    if (fs.existsSync(readablePath)) {
+        fs.unlinkSync(readablePath);
+        if (readablePath !== canonicalPath && fs.existsSync(canonicalPath)) {
+            fs.unlinkSync(canonicalPath);
+        }
+        return { backend: "file", removed: true };
+    }
+    const { keytar, reason } = await resolveKeytar();
+    if (keytar) {
+        try {
+            const removed = await keytar.deletePassword(SERVICE, ACCOUNT);
+            return { backend: "keytar", removed: removed || hadSession };
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Failed to clear token from OS keychain: ${error.message}`);
+            }
+            throw new Error("Failed to clear token from OS keychain.");
+        }
+    }
+    if (hadSession) {
+        return { backend: "session", removed: true };
+    }
+    throw new Error(`No credential backend available to clear credentials (${reason ?? "unknown reason"}).`);
+}
+// Test seam: forcibly clear the in-memory session credential. Not exported via
+// the package surface for end users — only used by unit tests.
+export function __resetSessionCredentialForTests() {
+    sessionCredential = null;
+}

package/dist/auth/deviceFlow.js

@@ -0,0 +1,89 @@
+const GITHUB_CLIENT_ID = "Iv1.b507a08c87ecfe98";
+const DEVICE_CODE_URL = "https://github.com/login/device/code";
+const ACCESS_TOKEN_URL = "https://github.com/login/oauth/access_token";
+export async function loginViaDeviceFlow() {
+    const start = await fetch(DEVICE_CODE_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+        body: new URLSearchParams({ client_id: GITHUB_CLIENT_ID, scope: "read:user" })
+    });
+    if (!start.ok) {
+        throw new Error(`Device flow init failed (${start.status}).`);
+    }
+    const payload = parseDeviceCodeResponse((await start.json()));
+    const verificationUrl = payload.verification_uri_complete ?? payload.verification_uri;
+    process.stdout.write(`Open ${verificationUrl} and enter code ${payload.user_code}\n`);
+    const deadline = Date.now() + payload.expires_in * 1000;
+    let intervalMs = Math.max(1, payload.interval) * 1000;
+    while (Date.now() < deadline) {
+        await sleep(intervalMs);
+        const poll = await fetch(ACCESS_TOKEN_URL, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+            body: new URLSearchParams({
+                client_id: GITHUB_CLIENT_ID,
+                device_code: payload.device_code,
+                grant_type: "urn:ietf:params:oauth:grant-type:device_code"
+            })
+        });
+        if (!poll.ok) {
+            throw new Error(`Access token poll failed (${poll.status}).`);
+        }
+        const tokenPayload = parseAccessTokenResponse((await poll.json()));
+        if (tokenPayload.access_token) {
+            return tokenPayload.access_token;
+        }
+        if (tokenPayload.error === "authorization_pending") {
+            continue;
+        }
+        if (tokenPayload.error === "slow_down") {
+            intervalMs += 1000;
+            continue;
+        }
+        if (tokenPayload.error === "expired_token") {
+            throw new Error("Device code expired before authorization completed.");
+        }
+        if (tokenPayload.error === "access_denied") {
+            throw new Error("Authorization was denied.");
+        }
+        const description = tokenPayload.error_description ? ` (${tokenPayload.error_description})` : "";
+        throw new Error(`Unexpected OAuth polling error: ${tokenPayload.error ?? "unknown"}${description}`);
+    }
+    throw new Error("Device authorization timed out.");
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function parseDeviceCodeResponse(value) {
+    if (!value || typeof value !== "object") {
+        throw new Error("Device flow init returned an invalid payload.");
+    }
+    const payload = value;
+    if (typeof payload.device_code !== "string" ||
+        typeof payload.user_code !== "string" ||
+        typeof payload.verification_uri !== "string" ||
+        typeof payload.expires_in !== "number" ||
+        typeof payload.interval !== "number") {
+        throw new Error("Device flow init response is missing required fields.");
+    }
+    if (payload.verification_uri_complete !== undefined && typeof payload.verification_uri_complete !== "string") {
+        throw new Error("Device flow init response contains an invalid verification_uri_complete field.");
+    }
+    return payload;
+}
+function parseAccessTokenResponse(value) {
+    if (!value || typeof value !== "object") {
+        throw new Error("Device flow poll returned an invalid payload.");
+    }
+    const payload = value;
+    if (payload.access_token !== undefined && typeof payload.access_token !== "string") {
+        throw new Error("Device flow poll response contains an invalid access_token field.");
+    }
+    if (payload.error !== undefined && typeof payload.error !== "string") {
+        throw new Error("Device flow poll response contains an invalid error field.");
+    }
+    if (payload.error_description !== undefined && typeof payload.error_description !== "string") {
+        throw new Error("Device flow poll response contains an invalid error_description field.");
+    }
+    return payload;
+}

package/dist/auth/ensureAuthenticated.js

@@ -0,0 +1,55 @@
+/**
+ * If no credential is stored, prompts the user to log in interactively. After
+ * a successful device flow, decides where to put the token: keychain (if
+ * available), or prompts plaintext / session / cancel.
+ *
+ * Caller is responsible for checking !opts.detach — this function assumes a
+ * TTY-attached foreground process and will throw if stdin is not a TTY when
+ * a prompt is needed.
+ */
+export async function ensureAuthenticatedInteractive(deps) {
+    const existing = await deps.inspectStoredCredential();
+    if (existing.stored) {
+        return;
+    }
+    if (!deps.isTty()) {
+        throw new Error("Not authenticated and stdin is not a TTY. Run `copillm auth login` first.");
+    }
+    deps.print("You are not logged in. copillm needs a GitHub OAuth token to talk to Copilot.\n");
+    const wantsLogin = await deps.confirm("Log in now?");
+    if (!wantsLogin) {
+        throw new Error("Aborted. Run `copillm auth login` when you're ready.");
+    }
+    const token = await deps.loginViaDeviceFlow();
+    const accountType = deps.loadAccountType();
+    // Try the normal save path first (keychain or pre-existing plaintext file).
+    // If that's not viable, fall back to an explicit user choice.
+    try {
+        const backend = await deps.saveStoredCredential(token, accountType);
+        deps.print(`Credentials stored via ${deps.describeBackend(backend)}.\n`);
+        return;
+    }
+    catch {
+        // Falls through to the explicit-choice prompt below. We swallow the
+        // specific error because the user is about to choose a path anyway.
+    }
+    deps.print("OS keychain is unavailable on this machine. Choose where to store the token:\n");
+    const choice = await deps.choose("  (p) plaintext file at ~/.copillm/credentials.json   (s) in-memory for this session only   (c) cancel", [
+        { key: "p", label: "plaintext", value: "plaintext" },
+        { key: "s", label: "session", value: "session" },
+        { key: "c", label: "cancel", value: "cancel" }
+    ]);
+    if (choice === "cancel") {
+        throw new Error("Login aborted.");
+    }
+    if (choice === "session") {
+        await deps.saveStoredCredential(token, accountType, { mode: "session" });
+        deps.print("Token kept in memory only — you'll need to log in again when this process exits.\n");
+        return;
+    }
+    // choice === "plaintext" — allow the plaintext fallback explicitly for this
+    // process. The credentials module checks this env var at save time.
+    deps.setEnv("COPILLM_ALLOW_PLAINTEXT_CREDENTIALS", "1");
+    await deps.saveStoredCredential(token, accountType);
+    deps.print("Credentials stored via credentials file.\n");
+}

package/dist/auth/githubIdentity.js

@@ -0,0 +1,42 @@
+import { loadStoredCredential } from "./credentials.js";
+import { getGithubUserSummary, GithubUserFetchError } from "../server/debugInfo.js";
+/**
+ * Inspection-style wrapper around loadStoredCredential + getGithubUserSummary
+ * that resolves the GitHub identity without ever exposing the token to the
+ * caller.
+ *
+ * Designed for the `auth status` code path: see the repo guideline
+ * "Don't wire status surfaces through loadStoredCredential". This helper is
+ * the only place the bearer touches the network from that code path, and the
+ * return value is shaped so the secret can't escape it.
+ *
+ * On any failure (no credential, network error, timeout, HTTP error) returns
+ * null so callers can gracefully fall back to existing offline output.
+ */
+export async function inspectGithubIdentity(options = {}) {
+    let credential;
+    try {
+        credential = await loadStoredCredential();
+    }
+    catch {
+        return null;
+    }
+    if (!credential) {
+        return null;
+    }
+    try {
+        const summary = await getGithubUserSummary(credential.token, {
+            timeoutMs: options.timeoutMs ?? 4_000
+        });
+        if (!summary.login) {
+            return null;
+        }
+        return { login: summary.login, name: summary.name };
+    }
+    catch (error) {
+        if (error instanceof GithubUserFetchError) {
+            return null;
+        }
+        return null;
+    }
+}