@dac-tech-team-tw/itsaplan-cli 0.1.0 → 0.3.0

package/dist/output.js

@@ -0,0 +1,261 @@
+import { CliError } from "./contracts.js";
+const scalarFields = (names) => Object.fromEntries(names.split(" ").map((name) => [name, true]));
+const projectFields = scalarFields("id ref key name description teamId teamName teamRef mcpEnabled teamMcpEnabled initiativesEnabled dashboardsEnabled documentsEnabled notesEnabled cyclesEnabled subtasksEnabled checklistsEnabled issueStatsEnabled pointsEstimateEnabled timeEstimateEnabled timeLoggingEnabled availableFeatures archivedAt createdAt updatedAt lastActivityAt isFavorite isHidden");
+const columnFields = scalarFields("id projectId name stateType color position wipLimit wipMode autoAssignUserId unavailable");
+const typeFields = scalarFields("id projectId name icon color isDefault position");
+const labelFields = scalarFields("id projectId groupId name color unavailable");
+const memberFields = scalarFields("id userId name email username image kind agentKind restrictedToUserId respondsToMention canReadWorkItems isAgent");
+const optionFields = scalarFields("id value color position unavailable");
+const customFieldFields = {
+    ...scalarFields("id projectId issueTypeId name fieldType memberScope showInBody position"),
+    options: optionFields,
+};
+const fieldValueFields = {
+    ...scalarFields("fieldId name fieldType value valueEnd optionIds"),
+    options: optionFields,
+};
+const issueFields = {
+    ...scalarFields("id projectId sequenceNumber identifier typeId assigneeUserId delegateUserId columnId parentId title description priority estimatePoints estimateMinutes loggedMinutes startDate dueDate position createdAt updatedAt completedAt archivedAt statusSince labelIds"),
+    initiative: scalarFields("id title status"),
+    cycle: scalarFields("id name status"),
+    fieldValues: fieldValueFields,
+    fields: fieldValueFields,
+    state: columnFields,
+};
+const relatedIssueFields = {
+    ...scalarFields("id projectId sequenceNumber identifier title columnId typeId archived"),
+    state: columnFields,
+    type: typeFields,
+};
+const feedValueFields = scalarFields("value id stateType repo number date");
+const feedFields = {
+    ...scalarFields("id issueId kind replyToId actorUserId actorName body action createdAt editedAt"),
+    payload: {
+        subject: feedValueFields,
+        from: feedValueFields,
+        to: feedValueFields,
+    },
+};
+// Replies use the same finite entry fields, without an unbounded recursive schema.
+feedFields.replies = { ...feedFields };
+const schemas = {
+    "project.list": projectFields,
+    "project.view": {
+        project: projectFields,
+        columns: columnFields,
+        issueTypes: typeFields,
+        labels: labelFields,
+        labelGroups: scalarFields("id projectId name color"),
+        assignees: memberFields,
+        customFields: customFieldFields,
+        issueTemplates: scalarFields("id name description titleTemplate descriptionTemplate typeId columnId priority assigneeUserId labelIds"),
+        viewer: scalarFields("role teamRole via"),
+        permissions: true,
+    },
+    "issue.list": {
+        ...issueFields,
+        parent: scalarFields("id identifier title"),
+        state: scalarFields("id name stateType unavailable"),
+    },
+    "issue.resolve": scalarFields("id issueId projectId identifier sequenceNumber projectRef"),
+    "issue.comments": feedFields,
+    "issue.activity": feedFields,
+    "issue.view": {
+        ...issueFields,
+        type: typeFields,
+        project: projectFields,
+        assignee: memberFields,
+        delegate: memberFields,
+        labels: labelFields,
+        customFields: customFieldFields,
+        parent: relatedIssueFields,
+        subtasks: relatedIssueFields,
+        links: { ...scalarFields("id kind direction"), issue: relatedIssueFields },
+        watchers: memberFields,
+        checklists: {
+            ...scalarFields("id title position"),
+            items: scalarFields("id content done position"),
+        },
+        attachments: scalarFields("id filename contentType sizeBytes createdAt url"),
+        comments: { items: feedFields, nextCursor: true },
+        development: {
+            ...scalarFields("id provider repository kind number title url state draft sourceBranch targetBranch headSha pipelineStatus pipelineUrl checkStatus updatedAt"),
+            checks: true,
+        },
+    },
+};
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const owns = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
+function selectedFields(kind, options) {
+    if (options.summary && options.fields !== undefined)
+        throw new CliError("CONFLICTING_ARGUMENTS", "--summary and --fields are mutually exclusive");
+    if (options.fields === undefined)
+        return [];
+    const fields = options.fields.split(",").map((field) => field.trim());
+    for (const field of fields) {
+        const parts = field.split(".");
+        if (!field ||
+            parts.some((part) => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(part) ||
+                part === "prototype" ||
+                owns(Object.prototype, part)))
+            throw new CliError("INVALID_FIELDS", "--fields must contain nonempty comma-separated dotted field names, without array indexes or prototype properties", 2, { kind, field });
+        let schema = schemas[kind];
+        for (const part of parts) {
+            if (schema === true || !owns(schema, part))
+                throw new CliError("INVALID_FIELDS", `Unknown --fields path ${JSON.stringify(field)} for ${kind}`, 2, { kind, field });
+            schema = schema[part];
+        }
+    }
+    return [...new Set(fields)];
+}
+/** Validate against command schemas even when the eventual result is empty. */
+export function validateOutput(kind, options) {
+    selectedFields(kind, options);
+}
+/** Only opt-in issue list state output needs project state lookup enrichment. */
+export function needsIssueStates(kind, options) {
+    const fields = selectedFields(kind, options);
+    return (kind === "issue.list" &&
+        (options.summary === true ||
+            fields.some((field) => field === "state" || field.startsWith("state."))));
+}
+function selection(fields) {
+    const root = { all: false, children: new Map() };
+    for (const field of fields) {
+        let node = root;
+        for (const part of field.split(".")) {
+            let child = node.children.get(part);
+            if (!child) {
+                child = { all: false, children: new Map() };
+                node.children.set(part, child);
+            }
+            node = child;
+        }
+        node.all = true;
+    }
+    return root;
+}
+function missingSelection(node, path, missing) {
+    if (node.all)
+        missing.add(path);
+    for (const [key, child] of node.children)
+        missingSelection(child, path ? `${path}.${key}` : key, missing);
+}
+function select(value, node, path, missing) {
+    if (node.all && node.children.size === 0)
+        return value;
+    // A present null is not an absent descendant, and array positions never shift.
+    if (value === null)
+        return null;
+    if (Array.isArray(value))
+        return value.map((entry, index) => select(entry, node, `${path}[${index}]`, missing));
+    const projected = {};
+    for (const [key, child] of node.children) {
+        const childPath = path ? `${path}.${key}` : key;
+        if (!isObject(value) || !owns(value, key) || value[key] === undefined) {
+            missingSelection(child, childPath, missing);
+            continue;
+        }
+        const nested = select(value[key], child, childPath, missing);
+        if (!node.all)
+            projected[key] = nested;
+    }
+    // A whole-field selection includes unknown future server properties unchanged.
+    return node.all ? value : projected;
+}
+const projectIdentity = selection(["id", "ref", "key", "name"]);
+const projectListSummary = selection(["id", "ref", "name"]);
+const projectViewSummary = selection([
+    "project.id",
+    "project.ref",
+    "project.key",
+    "project.name",
+    "columns.id",
+    "columns.name",
+    "columns.stateType",
+    "issueTypes.id",
+    "issueTypes.name",
+    "labels.id",
+    "labels.name",
+    "customFields",
+]);
+const issueListSummary = selection(["id", "identifier", "title", "columnId"]);
+const stateSummary = selection(["id", "name", "stateType"]);
+function summary(kind, value, path, missing) {
+    if (kind === "project.list")
+        return select(value, projectListSummary, path, missing);
+    if (kind === "project.view")
+        return select(value, projectViewSummary, path, missing);
+    if (kind === "issue.view" && isObject(value)) {
+        const projected = { ...value };
+        if (owns(value, "project"))
+            projected.project = select(value.project, projectIdentity, "project", missing);
+        else
+            missing.add("project");
+        return projected;
+    }
+    if (kind === "issue.list" && isObject(value)) {
+        const projected = select(value, issueListSummary, path, missing);
+        const state = value.state;
+        projected.state =
+            isObject(state) && state.unavailable === true
+                ? state
+                : select(state, stateSummary, `${path}.state`, missing);
+        return projected;
+    }
+    // Resolve is already compact; feed bodies, payloads and replies stay lossless.
+    return value;
+}
+/** Shape data only: serialization, redaction and fetching belong to callers. */
+export function projectOutput(kind, result, options) {
+    // Error and write-outcome envelopes must remain exactly as received.
+    if (result.error !== undefined)
+        return result;
+    const fields = selectedFields(kind, options);
+    if (!options.summary && options.fields === undefined)
+        return result;
+    const missing = new Set();
+    const tree = selection(fields);
+    const project = (value, path) => {
+        if (options.summary)
+            return summary(kind, value, path, missing);
+        const projected = select(value, tree, path, missing);
+        // Unknown list states retain their diagnostic identity even for state.name.
+        if (kind === "issue.list" &&
+            tree.children.has("state") &&
+            isObject(value) &&
+            isObject(value.state) &&
+            value.state.unavailable === true &&
+            isObject(projected))
+            projected.state = { id: value.state.id, unavailable: true };
+        return projected;
+    };
+    const list = kind === "project.list" ||
+        kind === "issue.list" ||
+        kind === "issue.comments" ||
+        kind === "issue.activity";
+    const data = options.summary &&
+        (kind === "issue.resolve" ||
+            kind === "issue.comments" ||
+            kind === "issue.activity")
+        ? result.data
+        : list && isObject(result.data) && Array.isArray(result.data.items)
+            ? {
+                ...result.data,
+                items: result.data.items.map((entry, index) => project(entry, `items[${index}]`)),
+            }
+            : project(result.data, "");
+    return {
+        ...result,
+        data,
+        meta: {
+            ...result.meta,
+            output: {
+                ...(isObject(result.meta?.output) ? result.meta?.output : {}),
+                mode: options.summary ? "summary" : "fields",
+                ...(options.summary ? {} : { fields }),
+                missing: [...missing],
+            },
+        },
+    };
+}

package/dist/project-config.d.ts

@@ -0,0 +1,2 @@
+import { type GlobalOptions, type Result } from "./contracts.js";
+export declare function runProjectConfig(action: "set" | "get" | "unset", options: GlobalOptions, ref?: string): Promise<Result>;

package/dist/project-config.js

@@ -0,0 +1,56 @@
+import { CliError, } from "./contracts.js";
+import { createContext, readUserConfig, resolveApiUrl, resolveProjectSelection, saveUserProject, } from "./config.js";
+import { runProject } from "./commands.js";
+export async function runProjectConfig(action, options, ref) {
+    try {
+        // Inspect directory trust even for local-only commands and explicit overrides.
+        const selection = await resolveProjectSelection(options);
+        const apiUrl = await resolveApiUrl(options);
+        if (!apiUrl)
+            throw new CliError("MISSING_API_URL", "Set ITSAPLAN_URL, use --api-url, or run auth login.");
+        if (action === "get")
+            return {
+                data: {
+                    action,
+                    apiUrl,
+                    savedProjectRef: (await readUserConfig()).project_defaults?.[apiUrl] ?? null,
+                    effectiveProjectRef: selection.projectRef ?? null,
+                    source: selection.source,
+                },
+            };
+        let projectRef;
+        if (action === "set") {
+            if (!ref || !/^(?:[A-Za-z0-9_-]+\.)?[A-Za-z][A-Za-z0-9_-]*$/u.test(ref))
+                throw new CliError("INVALID_PROJECT", "Use a project key or team.KEY ref.");
+            const ctx = await createContext({ ...options, project: ref });
+            if (!ctx.auth.tokenAvailable)
+                throw new CliError("AUTHENTICATION_REQUIRED", "Authenticate before validating a default project.", 3);
+            // Reuse project view's complete setup validation, not just a permissive ref lookup.
+            const result = await runProject(ctx, "view", ref);
+            const project = result.data.project;
+            projectRef = project.ref;
+            if (!/^[A-Za-z0-9_-]+\.[A-Za-z][A-Za-z0-9_-]*$/u.test(projectRef) ||
+                project.key !== projectRef.split(".")[1] ||
+                (ref.includes(".") ? projectRef !== ref : project.key !== ref))
+                throw new CliError("PROJECT_MISMATCH", "The API returned a different project ref; local configuration was not changed.");
+        }
+        const { changed } = await saveUserProject(apiUrl, projectRef);
+        return {
+            data: { action, apiUrl, projectRef: projectRef ?? null, changed },
+            outcome: changed ? "applied" : "not_applied",
+            verification: "passed",
+        };
+    }
+    catch (error) {
+        if (action === "get")
+            throw error;
+        if (error instanceof CliError)
+            throw new CliError(error.code, error.message, error.exitCode, {
+                ...error.details,
+                outcome: "not_applied",
+                verification: "not_run",
+                retryable: false,
+            });
+        throw new CliError("LOCAL_OPERATION_FAILED", "The default project was not changed; no API write was sent.", 1, { outcome: "not_applied", verification: "not_run", retryable: false });
+    }
+}

package/dist/writes.d.ts

@@ -2,7 +2,7 @@ import { type Actor, type Context, type ObjectData, type Result } from "./contra
 import { type IssueOptions } from "./issues.js";
 /** Preflight failures are never mistaken for a write with an unknown outcome. */
 export declare function withWrite(options: IssueOptions, operation: (actor: Actor) => Promise<Result>): Promise<Result>;
-export declare function preview(ctx: Context, actor: Actor, data: ObjectData, path: string, body: ObjectData, warnings?: string[]): Promise<Result>;
-export declare function writeFailure(error: unknown, data: ObjectData, actor: Actor): Result;
-export declare function verificationFailed(data: ObjectData, actor: Actor): Result;
+export declare function preview(ctx: Context, actor: Actor, data: ObjectData, path: string, body: ObjectData, warnings?: string[], method?: string): Promise<Result>;
+export declare function writeFailure(error: unknown, data: ObjectData, actor: Actor, resource?: string): Result;
+export declare function verificationFailed(data: ObjectData, actor: Actor, resource?: string): Result;
 export declare function applied(data: ObjectData, actor: Actor): Result;

package/dist/writes.js

@@ -26,13 +26,13 @@ export async function withWrite(options, operation) {
         });
     }
 }
-export async function preview(ctx, actor, data, path, body, warnings = []) {
+export async function preview(ctx, actor, data, path, body, warnings = [], method = "POST") {
     return {
         data: {
             ...data,
             dryRun: true,
             identity: await me(ctx),
-            request: { method: "POST", path, body },
+            request: { method, path, body },
             warnings: [
                 "Preview sends no writes and does not guarantee server permissions or concurrent state.",
                 ...warnings,
@@ -43,14 +43,14 @@ export async function preview(ctx, actor, data, path, body, warnings = []) {
         verification: "not_run",
     };
 }
-export function writeFailure(error, data, actor) {
-    const result = issueWriteFailure(error, data, actor, "document or relation");
+export function writeFailure(error, data, actor, resource = "document or relation") {
+    const result = issueWriteFailure(error, data, actor, resource);
     if (result.outcome === "unknown")
         delete data.changed;
     return result;
 }
-export function verificationFailed(data, actor) {
-    return issueVerificationFailed(data, actor, "document or relation");
+export function verificationFailed(data, actor, resource = "document or relation") {
+    return issueVerificationFailed(data, actor, resource);
 }
 export function applied(data, actor) {
     return { data, meta: { actor }, outcome: "applied", verification: "passed" };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dac-tech-team-tw/itsaplan-cli",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Composable It's a Plan CLI for humans and coding agents",
   "type": "module",
   "repository": {
@@ -27,6 +27,7 @@
     "build": "tsc",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
     "test": "tsx --test test/*.test.ts",
+    "release": "node scripts/publish-local.mjs",
     "format": "prettier --write src test package.json tsconfig*.json",
     "prepack": "npm run build",
     "install-local": "node scripts/install-local.mjs"