@dac-tech-team-tw/itsaplan-cli 0.0.0-stage → 0.2.0

package/dist/contracts.js

@@ -0,0 +1,14 @@
+import { readFileSync } from "node:fs";
+export class CliError extends Error {
+    code;
+    exitCode;
+    details;
+    constructor(code, message, exitCode = 2, details = {}) {
+        super(message);
+        this.code = code;
+        this.exitCode = exitCode;
+        this.details = details;
+    }
+}
+export const CLI_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+export const API_BASELINE = "1.9.0";

package/dist/development.d.ts

@@ -0,0 +1,9 @@
+import { type Context, type Result } from "./contracts.js";
+import { type IssueOptions } from "./issues.js";
+export interface DevelopmentOptions extends IssueOptions {
+    repository?: string;
+    number?: string;
+    page?: string;
+    state?: string;
+}
+export declare function runDevelopment(ctx: Context, action: string, identifier: string | undefined, options: DevelopmentOptions): Promise<Result>;

package/dist/development.js

@@ -0,0 +1,220 @@
+import { CliError, } from "./contracts.js";
+import { integer, object, objects, positive, publicData, resolve, } from "./issues.js";
+import { applied, preview, verificationFailed, withWrite, writeFailure, } from "./writes.js";
+const providers = ["github", "gitlab", "gitea", "forgejo", "bitbucket"];
+const nonempty = (value) => typeof value === "string" && value.trim().length > 0;
+function unsupported(message) {
+    throw new CliError("UNSUPPORTED_RESPONSE", message);
+}
+function required(value, flag) {
+    if (value === undefined)
+        throw new CliError("INVALID_ARGUMENT", `${flag} is required`);
+    return integer(value, flag);
+}
+async function repositories(ctx, issueId) {
+    const values = objects(await ctx.client.request(`/issues/${issueId}/development/repositories`), "connected repositories");
+    const ids = new Set();
+    return values.map((value) => {
+        if (!positive(value.id) ||
+            !["github", "gitlab"].includes(String(value.provider)) ||
+            !nonempty(value.fullName) ||
+            !nonempty(value.webUrl) ||
+            ids.has(value.id))
+            unsupported("Connected repository response has invalid or ambiguous identity");
+        ids.add(value.id);
+        return {
+            id: value.id,
+            provider: value.provider,
+            fullName: value.fullName,
+            webUrl: value.webUrl,
+        };
+    });
+}
+function connected(values, id) {
+    const repository = values.find((value) => value.id === id);
+    if (!repository)
+        throw new CliError("REPOSITORY_NOT_CONNECTED", "The selected repository is not connected to this issue's project");
+    return repository;
+}
+function link(value) {
+    const entry = object(value, "development link");
+    if (!positive(entry.id) ||
+        !providers.includes(String(entry.provider)) ||
+        !nonempty(entry.repository) ||
+        !["pull_request", "branch"].includes(String(entry.kind)) ||
+        (entry.kind === "pull_request"
+            ? !positive(entry.number)
+            : entry.number !== null || !nonempty(entry.sourceBranch)))
+        unsupported("Development link response is missing stable identity");
+    return entry;
+}
+function links(item) {
+    // Both exact issue routes expose `development` in the API baseline.
+    const values = objects(item.development, "issue development").map(link);
+    const ids = new Set();
+    const identities = new Set();
+    for (const value of values) {
+        const identity = JSON.stringify([
+            value.kind,
+            value.provider,
+            value.repository,
+            value.kind === "pull_request" ? value.number : value.sourceBranch,
+        ]);
+        if (ids.has(value.id) || identities.has(identity))
+            throw new CliError("CONFLICT", "Issue development links contain ambiguous identities; no write was sent", 5);
+        ids.add(value.id);
+        identities.add(identity);
+    }
+    return values;
+}
+function matches(value, repository, number) {
+    return (value.kind === "pull_request" &&
+        value.provider === repository.provider &&
+        value.repository === repository.fullName &&
+        value.number === number);
+}
+function pullRequests(value) {
+    const items = objects(value, "pull requests");
+    const numbers = new Set();
+    for (const item of items) {
+        if (!positive(item.number) ||
+            typeof item.title !== "string" ||
+            !(item.url === null || typeof item.url === "string") ||
+            !["open", "merged", "closed"].includes(String(item.state)) ||
+            typeof item.draft !== "boolean" ||
+            !(item.sourceBranch === null || typeof item.sourceBranch === "string") ||
+            typeof item.targetBranch !== "string" ||
+            !(item.headSha === null || typeof item.headSha === "string") ||
+            typeof item.updatedAt !== "string" ||
+            typeof item.linked !== "boolean" ||
+            numbers.has(item.number))
+            unsupported("Pull request response has invalid or ambiguous metadata");
+        numbers.add(item.number);
+    }
+    return items;
+}
+export async function runDevelopment(ctx, action, identifier, options) {
+    if (action === "link-pr")
+        return withWrite(options, async (actor) => {
+            const repositoryId = required(options.repository, "--repository");
+            const number = required(options.number, "--number");
+            const { item } = await resolve(ctx, identifier, options);
+            const repository = connected(await repositories(ctx, item.id), repositoryId);
+            const existing = links(item).find((value) => matches(value, repository, number));
+            const data = {
+                action: "link-pr",
+                changed: false,
+                alreadyLinked: Boolean(existing),
+                issueId: item.id,
+                identifier: item.identifier,
+                repositoryId,
+                provider: repository.provider,
+                repository: repository.fullName,
+                number,
+            };
+            if (existing)
+                data.linkId = existing.id;
+            const path = `/issues/${item.id}/development`;
+            const body = { repositoryId, number };
+            if (options.dryRun)
+                return preview(ctx, actor, data, path, body, [
+                    "Exact pull request existence is verified by the server on write; discovery is not proof that this number exists.",
+                    ...(existing
+                        ? [
+                            "This association already exists; a normal invocation is a no-op.",
+                        ]
+                        : []),
+                ]);
+            if (existing)
+                return {
+                    data,
+                    meta: { actor },
+                    outcome: "not_applied",
+                    verification: "passed",
+                };
+            let response;
+            try {
+                // The server looks up this exact number (including closed PRs) and upserts its identity.
+                response = await ctx.client.request(path, { method: "POST", body });
+            }
+            catch (error) {
+                return writeFailure(error, data, actor);
+            }
+            data.changed = true;
+            if (typeof response === "object" &&
+                response !== null &&
+                !Array.isArray(response)) {
+                const observed = response;
+                if (positive(observed.id))
+                    data.linkId = observed.id;
+            }
+            try {
+                const verified = link(response);
+                if (matches(verified, repository, number))
+                    return applied({ ...data, linkId: verified.id }, actor);
+            }
+            catch {
+                // A malformed accepted response can still be verified by the exact issue read.
+            }
+            try {
+                const current = object(await ctx.client.request(`/issues/${item.id}`), "issue");
+                if (current.id !== item.id || current.projectId !== item.projectId)
+                    unsupported("Verification returned a different issue");
+                const verified = links(current).find((value) => matches(value, repository, number));
+                if (verified)
+                    return applied({ ...data, linkId: verified.id }, actor);
+            }
+            catch {
+                // Never resend an accepted write when verification cannot establish the identity.
+            }
+            return verificationFailed(data, actor);
+        });
+    if (!["repositories", "pull-requests", "development"].includes(action))
+        throw new CliError("UNKNOWN_ACTION", `Unsupported development action: ${action}`);
+    if (options.limit !== undefined)
+        throw new CliError("UNSUPPORTED_PAGINATION", "Development commands do not support --limit; pull-requests uses --page and --state");
+    const { item } = await resolve(ctx, identifier, options);
+    const scope = { issueId: item.id, identifier: item.identifier };
+    if (action === "development") {
+        const items = links(item);
+        return {
+            data: { ...scope, items: publicData(items), nextCursor: null },
+            meta: { returned: items.length, completeness: "complete" },
+        };
+    }
+    if (action === "repositories") {
+        const items = await repositories(ctx, item.id);
+        return {
+            data: { ...scope, items, nextCursor: null },
+            meta: { returned: items.length, completeness: "complete" },
+        };
+    }
+    const repositoryId = required(options.repository, "--repository");
+    const page = options.page === undefined ? 1 : integer(options.page, "--page");
+    const state = options.state ?? "open";
+    if (state !== "open" && state !== "all")
+        throw new CliError("INVALID_ARGUMENT", "--state must be open or all");
+    const repository = connected(await repositories(ctx, item.id), repositoryId);
+    const response = object(await ctx.client.request(`/issues/${item.id}/development/repositories/${repositoryId}/pull-requests`, { query: { page, state } }), "pull request page");
+    const items = pullRequests(response.pullRequests);
+    if (response.nextPage !== null &&
+        (!positive(response.nextPage) || response.nextPage <= page))
+        unsupported("Pull request response has invalid nextPage");
+    return {
+        data: {
+            ...scope,
+            repositoryId,
+            provider: repository.provider,
+            repository: repository.fullName,
+            items: publicData(items),
+            nextPage: response.nextPage,
+        },
+        meta: {
+            page,
+            state,
+            returned: items.length,
+            completeness: page === 1 && response.nextPage === null ? "complete" : "partial",
+            completenessScope: "selected repository and state filter",
+        },
+    };
+}

package/dist/documents.d.ts

@@ -0,0 +1,9 @@
+import { type Context, type Result } from "./contracts.js";
+import { type IssueOptions } from "./issues.js";
+export interface DocumentOptions extends IssueOptions {
+    title?: string;
+    visibility?: string;
+    document?: string;
+}
+export declare function runDocument(ctx: Context, action: string, documentId: string | undefined, options: DocumentOptions): Promise<Result>;
+export declare function runIssueDocument(ctx: Context, action: string, identifier: string | undefined, options: DocumentOptions): Promise<Result>;

package/dist/documents.js

@@ -0,0 +1,256 @@
+import { CliError, } from "./contracts.js";
+import { getProject, integer, object, objects, positive, projectRef, publicData, readBody, resolve, setupFor, } from "./issues.js";
+import { applied, preview, verificationFailed, withWrite, writeFailure, } from "./writes.js";
+const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function unsupported(message) {
+    throw new CliError("UNSUPPORTED_RESPONSE", message);
+}
+function scopeFor(setup) {
+    if (!positive(setup.project.id) || typeof setup.project.ref !== "string")
+        unsupported("Project response is missing stable identifiers");
+    return {
+        projectId: setup.project.id,
+        projectRef: projectRef(setup.project.ref),
+    };
+}
+async function selectedScope(ctx, options) {
+    const ref = options.project ?? ctx.options.project ?? ctx.project;
+    if (ref === undefined)
+        throw new CliError("PROJECT_REQUIRED", "Provide --project team.KEY or configure a project");
+    return scopeFor(await getProject(ctx, projectRef(ref)));
+}
+function visibility(isPrivate) {
+    return {
+        visibility: isPrivate ? "private" : "project",
+        visibilityDescription: isPrivate
+            ? "Private to the document owner; not internet-public."
+            : "Visible to permitted project members; not internet-public.",
+    };
+}
+function pathFor(scope, documentId) {
+    return `/projects/${encodeURIComponent(scope.projectRef)}/documents${documentId === undefined ? "" : `/${documentId}`}`;
+}
+function document(value, scope, id) {
+    const entry = object(value, "document");
+    if (!positive(entry.id) || !positive(entry.projectId))
+        unsupported("Document response is missing stable identifiers");
+    if (entry.id !== id || entry.projectId !== scope.projectId)
+        throw new CliError("PROJECT_CONFLICT", "The document does not match the selected document and project");
+    if (typeof entry.title !== "string" ||
+        typeof entry.content !== "string" ||
+        typeof entry.isPrivate !== "boolean" ||
+        (entry.archivedAt !== null && typeof entry.archivedAt !== "string"))
+        unsupported("Document response is missing content, visibility, or archive status");
+    return entry;
+}
+async function readDocument(ctx, scope, id) {
+    return document(await ctx.client.request(pathFor(scope, id)), scope, id);
+}
+function issueLinks(value, scope) {
+    const entries = objects(value, "document issue links");
+    const key = scope.projectRef.slice(scope.projectRef.lastIndexOf(".") + 1);
+    if (entries.some((entry) => !positive(entry.issueId) ||
+        !positive(entry.sequenceNumber) ||
+        entry.identifier !== `${key}-${entry.sequenceNumber}` ||
+        typeof entry.title !== "string" ||
+        typeof entry.archived !== "boolean" ||
+        typeof entry.createdAt !== "string" ||
+        (entry.projectId !== undefined && entry.projectId !== scope.projectId)))
+        unsupported("Document issue links are missing identifiers or contain foreign project entries");
+    return entries;
+}
+async function readIssueLinks(ctx, scope, documentId) {
+    return issueLinks(await ctx.client.request(`${pathFor(scope, documentId)}/issues`), scope);
+}
+function finalContent(body, actor) {
+    const name = actor.name === "codex" ? "Codex" : "Claude";
+    const content = actor.kind === "agent" ? `${body.trimEnd()}\n\n— by ${name} via iap` : body;
+    if (content.length > 250000)
+        throw new CliError("BODY_LENGTH", "The final document content including its footer must be at most 250000 characters");
+    return content;
+}
+async function create(ctx, documentId, options, actor) {
+    if (documentId !== undefined)
+        throw new CliError("CONFLICTING_ARGUMENTS", "document create does not accept a document ID");
+    if (options.visibility !== "project" && options.visibility !== "private")
+        throw new CliError("VISIBILITY_REQUIRED", "Provide --visibility project|private; project visibility is not internet-public");
+    if (options.title === undefined ||
+        !options.title.trim() ||
+        options.title.length > 255)
+        throw new CliError("TITLE_LENGTH", "Provide a nonempty --title of at most 255 characters");
+    const body = await readBody(options);
+    if (body === undefined || !body.trim())
+        throw new CliError("BODY_REQUIRED", "Provide nonempty --body or --body-file");
+    const content = finalContent(body, actor);
+    const scope = await selectedScope(ctx, options);
+    const requestBody = {
+        title: options.title,
+        content,
+        isPrivate: options.visibility === "private",
+    };
+    const path = pathFor(scope);
+    const data = {
+        action: "create",
+        ...scope,
+        ...visibility(requestBody.isPrivate),
+        changed: false,
+    };
+    if (options.dryRun)
+        return preview(ctx, actor, data, path, requestBody);
+    let response;
+    try {
+        response = await ctx.client.request(path, {
+            method: "POST",
+            body: requestBody,
+        });
+    }
+    catch (error) {
+        return writeFailure(error, data, actor);
+    }
+    data.changed = true;
+    if (record(response) && positive(response.id))
+        data.documentId = response.id;
+    const matches = (value) => record(value) &&
+        value.id === data.documentId &&
+        positive(value.id) &&
+        value.projectId === scope.projectId &&
+        value.title === requestBody.title &&
+        value.content === content &&
+        value.isPrivate === requestBody.isPrivate;
+    if (matches(response))
+        return applied(data, actor);
+    if (positive(data.documentId)) {
+        try {
+            if (matches(await ctx.client.request(pathFor(scope, data.documentId))))
+                return applied(data, actor);
+        }
+        catch {
+            // An accepted create keeps its stable ID even when the verification read fails.
+        }
+    }
+    return verificationFailed(data, actor);
+}
+export async function runDocument(ctx, action, documentId, options) {
+    if (action === "create")
+        return withWrite(options, (actor) => create(ctx, documentId, options, actor));
+    if (action !== "view" && action !== "issues")
+        throw new CliError("UNKNOWN_ACTION", `Unsupported document action: ${action}`);
+    if (documentId === undefined)
+        throw new CliError("DOCUMENT_REQUIRED", "Provide a document ID");
+    const id = integer(documentId, "document ID");
+    const scope = await selectedScope(ctx, options);
+    const entry = await readDocument(ctx, scope, id);
+    const data = {
+        documentId: id,
+        ...scope,
+        ...visibility(entry.isPrivate),
+    };
+    if (action === "view")
+        return { data: { ...object(publicData(entry), "document"), ...data } };
+    const entries = await readIssueLinks(ctx, scope, id);
+    return {
+        data: { ...data, items: publicData(entries), nextCursor: null },
+        meta: {
+            returned: entries.length,
+            completeness: "complete",
+            scope: "caller-visible document links",
+        },
+    };
+}
+async function linkDocument(ctx, identifier, options, actor) {
+    if (options.document === undefined)
+        throw new CliError("DOCUMENT_REQUIRED", "Provide --document with an existing document ID");
+    const documentId = integer(options.document, "--document");
+    const { item, ref } = await resolve(ctx, identifier, options);
+    const scope = scopeFor(await setupFor(ctx, item, ref));
+    const entry = await readDocument(ctx, scope, documentId);
+    if (entry.archivedAt !== null)
+        throw new CliError("DOCUMENT_ARCHIVED", "Archived documents cannot be linked; restore the document first");
+    // The server permits linking a locked document; locking only restricts content changes.
+    const links = await readIssueLinks(ctx, scope, documentId);
+    const matches = (link) => link.issueId === item.id &&
+        link.sequenceNumber === item.sequenceNumber &&
+        link.identifier === item.identifier;
+    const alreadyLinked = links.some(matches);
+    const data = {
+        action: "link-document",
+        documentId,
+        issueId: item.id,
+        identifier: item.identifier,
+        ...scope,
+        ...visibility(entry.isPrivate),
+        changed: false,
+        alreadyLinked,
+    };
+    const path = `${pathFor(scope, documentId)}/issues`;
+    const body = { issueId: item.id };
+    if (options.dryRun)
+        return preview(ctx, actor, data, path, body, alreadyLinked
+            ? [
+                "This association already exists; a normal invocation is a no-op. The server rejects duplicate POSTs with 409.",
+            ]
+            : undefined);
+    if (alreadyLinked)
+        return {
+            data,
+            meta: { actor },
+            outcome: "not_applied",
+            verification: "passed",
+        };
+    let response;
+    try {
+        response = await ctx.client.request(path, { method: "POST", body });
+    }
+    catch (error) {
+        return writeFailure(error, data, actor);
+    }
+    data.changed = true;
+    try {
+        if (issueLinks([response], scope).some(matches))
+            return applied(data, actor);
+    }
+    catch {
+        // A malformed or unrelated accepted response needs an actual association read.
+    }
+    try {
+        if ((await readIssueLinks(ctx, scope, documentId)).some(matches))
+            return applied(data, actor);
+    }
+    catch {
+        // Preserve both known resource IDs on an accepted but unverifiable link.
+    }
+    return verificationFailed(data, actor);
+}
+export async function runIssueDocument(ctx, action, identifier, options) {
+    if (action === "link-document")
+        return withWrite(options, (actor) => linkDocument(ctx, identifier, options, actor));
+    if (action !== "documents")
+        throw new CliError("UNKNOWN_ACTION", `Unsupported issue document action: ${action}`);
+    const { item, ref } = await resolve(ctx, identifier, options);
+    const scope = scopeFor(await setupFor(ctx, item, ref));
+    const entries = objects(await ctx.client.request(`${pathFor(scope)}/for-issue/${item.id}`), "issue document links");
+    if (entries.some((entry) => !positive(entry.documentId) ||
+        typeof entry.title !== "string" ||
+        typeof entry.isPrivate !== "boolean" ||
+        typeof entry.archived !== "boolean" ||
+        typeof entry.createdAt !== "string" ||
+        (entry.projectId !== undefined && entry.projectId !== scope.projectId)))
+        unsupported("Issue document links are missing identifiers, visibility, or contain foreign project entries");
+    return {
+        data: {
+            issueId: item.id,
+            identifier: item.identifier,
+            ...scope,
+            items: entries.map((entry) => ({
+                ...object(publicData(entry), "document link"),
+                ...visibility(entry.isPrivate),
+            })),
+            nextCursor: null,
+        },
+        meta: {
+            returned: entries.length,
+            completeness: "complete",
+            scope: "caller-visible document links",
+        },
+    };
+}

package/dist/http.d.ts

@@ -0,0 +1,11 @@
+import { type Client, type RequestOptions } from "./contracts.js";
+export declare function registerSecret(token: string): void;
+export declare function redact(value: unknown): unknown;
+export declare function validateRelativePath(input: string): string;
+export declare function classifyWriteFailure(error: unknown): "not_applied" | "unknown";
+export declare class HttpClient implements Client {
+    private readonly apiUrl;
+    private readonly token;
+    constructor(apiUrl: string, token: string | undefined);
+    request(input: string, options?: RequestOptions): Promise<unknown>;
+}