@skrr-ai/cli 0.1.8

package/dist/lib/task-tree.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTaskTree = buildTaskTree;
+exports.buildTaskForest = buildTaskForest;
+exports.fetchGoalTaskForest = fetchGoalTaskForest;
+exports.printTaskTree = printTaskTree;
+exports.printTaskForest = printTaskForest;
+exports.countDescendants = countDescendants;
+const data_provider_1 = require("@skrr-ai/data-provider");
+const tasks_1 = require("./tasks");
+function buildTaskTree(root, descendants) {
+    const byParent = groupChildrenByParent(descendants);
+    return attachChildren({ ...root, children: [] }, byParent, new Set());
+}
+function buildTaskForest(tasks) {
+    const nodes = tasks.map((task) => ({ ...task, children: [] }));
+    const ids = new Set(nodes.map((node) => (0, tasks_1.taskId)(node)).filter(Boolean));
+    const byParent = groupChildrenByParent(nodes);
+    const roots = nodes.filter((node) => {
+        const id = (0, tasks_1.taskId)(node);
+        const parentId = stringValue(node.parentId);
+        return !parentId || parentId === id || !ids.has(parentId);
+    });
+    const candidateRoots = roots.length > 0 ? roots : nodes;
+    const seen = new Set();
+    const forest = [];
+    for (const root of sortTaskNodes(candidateRoots)) {
+        const id = (0, tasks_1.taskId)(root);
+        if (id && seen.has(id))
+            continue;
+        forest.push(attachChildren(root, byParent, new Set(), seen));
+    }
+    return forest;
+}
+async function fetchGoalTaskForest({ goalId, limit = 500, cursor, }) {
+    const maxTasks = normalizeLimit(limit, 500);
+    const tasks = [];
+    let nextCursor = cursor || undefined;
+    let hasMore = false;
+    while (tasks.length < maxTasks) {
+        const pageLimit = Math.min(maxTasks - tasks.length, 500);
+        const response = await data_provider_1.dataService.listGoalTasks(goalId, {
+            limit: pageLimit,
+            ...(nextCursor ? { cursor: nextCursor } : {}),
+        });
+        const items = (0, tasks_1.listItems)(response);
+        tasks.push(...items);
+        nextCursor =
+            typeof response.next_cursor === 'string' && response.next_cursor.length > 0
+                ? response.next_cursor
+                : undefined;
+        hasMore = Boolean(response.has_more && nextCursor);
+        if (items.length === 0) {
+            hasMore = false;
+            nextCursor = undefined;
+            break;
+        }
+        if (!hasMore)
+            break;
+    }
+    const trees = buildTaskForest(tasks);
+    return {
+        object: 'goal_task_forest',
+        goalId,
+        taskCount: tasks.length,
+        rootCount: trees.length,
+        has_more: hasMore,
+        next_cursor: nextCursor ?? null,
+        trees,
+    };
+}
+function printTaskTree(node, log, prefix = '', isRoot = true, isLast = true) {
+    const connector = isRoot ? '' : isLast ? '`- ' : '|- ';
+    log(`${prefix}${connector}${formatNode(node)}`);
+    const children = Array.isArray(node.children) ? node.children : [];
+    const childPrefix = isRoot ? '' : `${prefix}${isLast ? '   ' : '|  '}`;
+    children.forEach((child, index) => {
+        printTaskTree(child, log, childPrefix, false, index === children.length - 1);
+    });
+}
+function printTaskForest(trees, log) {
+    trees.forEach((tree, index) => {
+        if (index > 0)
+            log('');
+        printTaskTree(tree, log);
+    });
+}
+function countDescendants(node) {
+    return node.children.reduce((count, child) => count + 1 + countDescendants(child), 0);
+}
+function groupChildrenByParent(tasks) {
+    const byParent = new Map();
+    for (const task of tasks) {
+        const node = task;
+        if (!Array.isArray(node.children))
+            node.children = [];
+        const parentId = stringValue(task.parentId);
+        if (!parentId)
+            continue;
+        const list = byParent.get(parentId) ?? [];
+        list.push(node);
+        byParent.set(parentId, list);
+    }
+    return byParent;
+}
+function attachChildren(node, byParent, path, globalSeen) {
+    const id = (0, tasks_1.taskId)(node);
+    if (!id || path.has(id))
+        return node;
+    path.add(id);
+    globalSeen?.add(id);
+    node.children = sortTaskNodes(byParent.get(id) ?? [])
+        .filter((child) => (0, tasks_1.taskId)(child) !== id)
+        .map((child) => attachChildren(child, byParent, new Set(path), globalSeen));
+    return node;
+}
+function sortTaskNodes(nodes) {
+    return [...nodes].sort((a, b) => {
+        const orderDelta = numericValue(a.order, Number.MAX_SAFE_INTEGER) -
+            numericValue(b.order, Number.MAX_SAFE_INTEGER);
+        if (orderDelta !== 0)
+            return orderDelta;
+        const aCreated = timestampValue(a.createdAt);
+        const bCreated = timestampValue(b.createdAt);
+        if (aCreated !== bCreated)
+            return bCreated - aCreated;
+        return formatNode(a).localeCompare(formatNode(b));
+    });
+}
+function formatNode(task) {
+    const ref = (0, tasks_1.taskRef)(task);
+    const title = String(task.title ?? '(no title)');
+    const status = task.status ? ` [${String(task.status)}]` : '';
+    return `${ref ? `${ref} ` : ''}${title}${status}`;
+}
+function normalizeLimit(value, fallback) {
+    if (!Number.isFinite(value) || !value || value <= 0)
+        return fallback;
+    return Math.floor(value);
+}
+function numericValue(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+function timestampValue(value) {
+    if (typeof value !== 'string' && !(value instanceof Date))
+        return 0;
+    const parsed = Date.parse(String(value));
+    return Number.isNaN(parsed) ? 0 : parsed;
+}
+function stringValue(value) {
+    return typeof value === 'string' ? value : '';
+}

package/dist/lib/task-view-render.d.ts

@@ -0,0 +1,71 @@
+/**
+ * task-view-render.ts — describe what a saved Task View actually SELECTS.
+ *
+ * A Task View is a query. `skrr views show` used to print its name and a browser
+ * URL, which answers "does this exist" and "where do I click", and never the
+ * one question worth asking. The whole object was already fetched and thrown
+ * away — same shape as `harnesses usage` measuring a number and not printing
+ * it.
+ *
+ * That lands hardest on this CLI's stated audience: a headless operator and a
+ * locally-running coding agent. Answering "what does this select?" with a URL
+ * sends the one reader who cannot open a browser to the one place they cannot
+ * go.
+ */
+export interface TaskViewFilters {
+    statuses?: string[];
+    priorities?: string[];
+    assignees?: string[];
+    labels?: string[];
+    goalIds?: string[];
+    projectIds?: string[];
+    search?: string;
+}
+export interface TaskViewLike {
+    name?: string;
+    id?: string;
+    viewType?: string;
+    visibility?: string;
+    workspaceId?: string;
+    spaceIds?: string[];
+    taskIds?: string[];
+    filters?: TaskViewFilters;
+    groupBy?: unknown;
+    sort?: unknown;
+}
+/**
+ * OSK-4859 — a view created with no active workspace comes back with no
+ * `workspaceId`, and the server then refuses to share it
+ * (`TASK_VIEW_NO_WORKSPACE`) because a view can only be shared TO a workspace.
+ * That is a dead end the caller cannot fix in place: `views update` accepts no
+ * workspace, so the only remedy is to re-create the view while a workspace is
+ * active. Say that at creation time, naming both ways to select one, instead of
+ * leaving the caller to discover it from a share attempt that fails.
+ *
+ * Returns null when the view HAS a workspace — the common, healthy case — so
+ * the caller can print unconditionally.
+ */
+export declare function unshareableViewWarning(view: TaskViewLike): string | null;
+/**
+ * The three fields `PATCH /api/task-views/:id` actually accepts. Kept here as
+ * the single client-side source of truth so both flag and `--from-json` paths
+ * refuse the same set, with the same explanatory copy.
+ */
+export declare const EDITABLE_VIEW_PATCH_FIELDS: readonly ["name", "description", "visibility"];
+/**
+ * OSK-4860 — `--from-json` keys bypassed the flag-only IMMUTABLE gate and hit
+ * the server's `.strict()` schema, which answers with a bare "Invalid task view
+ * patch" naming nothing. Inspect the body here so the same refusal the flags
+ * give can name the offending keys. Returns the keys the server would reject,
+ * in body order; empty when the body is clean.
+ */
+export declare function immutableViewPatchKeys(body: Record<string, unknown>): string[];
+/**
+ * Lines describing the view's query, skipping anything empty.
+ *
+ * Empty filter arrays are omitted deliberately: `priorities: []` means "not
+ * filtered on priority", and printing it as a row invites the reader to think
+ * a constraint exists. A view with no constraints at all says so once, rather
+ * than listing six empty ones.
+ */
+export declare function describeTaskView(view: TaskViewLike): string[];

package/dist/lib/task-view-render.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * task-view-render.ts — describe what a saved Task View actually SELECTS.
+ *
+ * A Task View is a query. `skrr views show` used to print its name and a browser
+ * URL, which answers "does this exist" and "where do I click", and never the
+ * one question worth asking. The whole object was already fetched and thrown
+ * away — same shape as `harnesses usage` measuring a number and not printing
+ * it.
+ *
+ * That lands hardest on this CLI's stated audience: a headless operator and a
+ * locally-running coding agent. Answering "what does this select?" with a URL
+ * sends the one reader who cannot open a browser to the one place they cannot
+ * go.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EDITABLE_VIEW_PATCH_FIELDS = void 0;
+exports.unshareableViewWarning = unshareableViewWarning;
+exports.immutableViewPatchKeys = immutableViewPatchKeys;
+exports.describeTaskView = describeTaskView;
+/**
+ * OSK-4859 — a view created with no active workspace comes back with no
+ * `workspaceId`, and the server then refuses to share it
+ * (`TASK_VIEW_NO_WORKSPACE`) because a view can only be shared TO a workspace.
+ * That is a dead end the caller cannot fix in place: `views update` accepts no
+ * workspace, so the only remedy is to re-create the view while a workspace is
+ * active. Say that at creation time, naming both ways to select one, instead of
+ * leaving the caller to discover it from a share attempt that fails.
+ *
+ * Returns null when the view HAS a workspace — the common, healthy case — so
+ * the caller can print unconditionally.
+ */
+function unshareableViewWarning(view) {
+    if (view.workspaceId)
+        return null;
+    return ('This view has no workspace, so it can never be shared. A view is created ' +
+        'in the active workspace, and none was selected. To make a shareable view, ' +
+        're-create it with `--workspace <id>`, or run `skrr workspaces use <id>` ' +
+        'first (see `skrr workspaces list`).');
+}
+/**
+ * The three fields `PATCH /api/task-views/:id` actually accepts. Kept here as
+ * the single client-side source of truth so both flag and `--from-json` paths
+ * refuse the same set, with the same explanatory copy.
+ */
+exports.EDITABLE_VIEW_PATCH_FIELDS = ['name', 'description', 'visibility'];
+/**
+ * OSK-4860 — `--from-json` keys bypassed the flag-only IMMUTABLE gate and hit
+ * the server's `.strict()` schema, which answers with a bare "Invalid task view
+ * patch" naming nothing. Inspect the body here so the same refusal the flags
+ * give can name the offending keys. Returns the keys the server would reject,
+ * in body order; empty when the body is clean.
+ */
+function immutableViewPatchKeys(body) {
+    const editable = new Set(exports.EDITABLE_VIEW_PATCH_FIELDS);
+    return Object.keys(body).filter((key) => !editable.has(key));
+}
+/** `groupBy` / `sort` are free-form; render an object as `k=v` rather than JSON. */
+function describeShape(value) {
+    if (value == null)
+        return null;
+    if (typeof value === 'string')
+        return value || null;
+    if (typeof value === 'object') {
+        const entries = Object.entries(value).filter(([, v]) => v !== null && v !== undefined && v !== '');
+        return entries.length ? entries.map(([k, v]) => `${k}=${String(v)}`).join(' ') : null;
+    }
+    return String(value);
+}
+/**
+ * Lines describing the view's query, skipping anything empty.
+ *
+ * Empty filter arrays are omitted deliberately: `priorities: []` means "not
+ * filtered on priority", and printing it as a row invites the reader to think
+ * a constraint exists. A view with no constraints at all says so once, rather
+ * than listing six empty ones.
+ */
+function describeTaskView(view) {
+    const lines = [];
+    const add = (label, value) => {
+        if (value)
+            lines.push(`  ${label.padEnd(12)} ${value}`);
+    };
+    add('type', view.viewType);
+    add('visibility', view.visibility);
+    const spaces = view.spaceIds ?? [];
+    if (spaces.length) {
+        add('spaces', `${spaces.length}: ${spaces.join(', ')}`);
+    }
+    else {
+        // A view with no space list spans everything the caller can see, which is
+        // a meaningful answer and not the same as "unset".
+        add('spaces', 'all spaces you can see');
+    }
+    const pinned = view.taskIds ?? [];
+    if (pinned.length) {
+        add('pinned tasks', `${pinned.length}: ${pinned.join(', ')}`);
+    }
+    const f = view.filters ?? {};
+    const filterRows = [
+        ['statuses', f.statuses],
+        ['priorities', f.priorities],
+        ['assignees', f.assignees],
+        ['labels', f.labels],
+        ['goals', f.goalIds],
+        ['projects', f.projectIds],
+    ];
+    let anyFilter = false;
+    for (const [label, values] of filterRows) {
+        if (values && values.length) {
+            anyFilter = true;
+            add(label, values.join(', '));
+        }
+    }
+    if (f.search) {
+        anyFilter = true;
+        add('search', `"${f.search}"`);
+    }
+    if (!anyFilter) {
+        add('filters', 'none — every task in scope');
+    }
+    add('group by', describeShape(view.groupBy));
+    add('sort', describeShape(view.sort));
+    return lines;
+}

package/dist/lib/tasks.d.ts

@@ -0,0 +1,195 @@
+/**
+ * The kinds `tasks events append --kind` will accept.
+ *
+ * A SECOND DECLARATION of a server-owned vocabulary — the authority is
+ * `TASK_WORK_EVENT_KINDS` in `packages/data-schemas/src/schema/taskWorkEvent.ts`,
+ * which the server validates against (`TaskWorkEvent.js` → `KINDS.has(kind)`).
+ * The CLI does not depend on `data-schemas` (it pulls mongoose), so the copy
+ * stays and `__tests__/task-work-event-kind-parity.spec.ts` pins it against the
+ * source — turning a silently rejected `--kind` into a build failure instead.
+ * Without the `options` list a bad value came back only as the server's generic
+ * `Invalid request data` / HTTP_400, naming neither the field nor the choices.
+ */
+export declare const TASK_WORK_EVENT_KINDS: readonly ["started", "checkpoint", "changed", "evidence", "decision", "blocker", "input_requested", "handoff", "verification", "completed", "failed", "lifecycle"];
+export type TaskRecord = Record<string, unknown>;
+export type TaskMutationGuardFailure = {
+    code: 'TASK_STATUS_REQUIRES_MOVE' | 'REPAIR_WITHOUT_ASSIGNEE_CHANGE';
+    message: string;
+};
+/**
+ * Release-pin repair is a mutation option, not a standalone operation. If no
+ * agent-assignee field is present the server has no continuity transition to
+ * run, so accepting the option would be a successful no-op.
+ */
+export declare function releasePinRepairGuard(payload: TaskRecord): TaskMutationGuardFailure | null;
+/**
+ * Guard the single-task `tasks update` surface. JSON input is intentionally
+ * open-ended, so the absence of a typed `--status` flag alone does not prevent
+ * callers from bypassing the canonical move endpoint.
+ */
+export declare function taskUpdateMutationGuard(payload: TaskRecord): TaskMutationGuardFailure | null;
+export type TaskCreateFlagValues = {
+    template?: string;
+    title?: string;
+    description?: string;
+    'description-format'?: string;
+    'external-key'?: string;
+    'default-agent'?: string;
+    priority?: string;
+    parent?: string;
+    space?: string;
+    goal?: string;
+    commitment?: string;
+    project?: string;
+    cycle?: string;
+    'source-conversation'?: string;
+    'source-message'?: string;
+    'spawned-by'?: string;
+    'spawn-reason'?: string;
+    'assignee-agent'?: string[];
+    'assignee-user'?: string[];
+    'execution-mode'?: string;
+    'start-date'?: string;
+    'due-date'?: string;
+    estimate?: number;
+    tag?: string[];
+    'label-id'?: string[];
+    worktree?: boolean;
+};
+/**
+ * Map the tri-state `--worktree` flag to the `executionIsolation` value.
+ * true ⇒ 'ephemeral', false ⇒ 'shared', undefined ⇒ undefined (inherit/leave).
+ */
+export declare function executionIsolationFromWorktreeFlag(worktree: boolean | undefined): 'shared' | 'ephemeral' | undefined;
+export declare function buildTaskCreatePayload(body: TaskRecord, flags?: TaskCreateFlagValues): TaskRecord;
+/**
+ * The Agent this CLI process is running AS, if any.
+ *
+ * Read ONLY from the session environment the daemon injects when it spawns a
+ * harness. There is deliberately no fallback that asks the server "which agents
+ * does this account own" — that question cannot identify the caller, and the
+ * answer it used to give was either a hard failure (two agents) or a confident
+ * wrong assignment (one agent that had nothing to do with this session).
+ *
+ * An empty result means "this caller is not running as an agent", which is a
+ * fact about the session, not a problem to solve.
+ */
+export declare function boundSessionAgentId(): string | undefined;
+export declare function applyDaemonSessionDefaults(payload: TaskRecord): void;
+export declare function validateTaskCreatePayload(payload: TaskRecord): string[];
+/** Stamp the unambiguous executor so CLI-authored tasks are explicit on day one. */
+export declare function applyInferredTaskExecutionMode(payload: TaskRecord): void;
+/**
+ * Stamp an executor only when the post-update assignee set is unambiguous.
+ * Existing fields participate when an upsert omits one assignee kind; this
+ * prevents an Agent-only patch from silently deciding an already-Human task.
+ */
+export declare function applyProspectiveTaskExecutionMode(payload: TaskRecord, existingTask?: TaskRecord | null): void;
+export declare function validateTaskCreateReferences(payload: TaskRecord): Promise<string[]>;
+export type TaskCreateScopeResolution = {
+    parentTask?: TaskRecord;
+    project?: TaskRecord;
+};
+/**
+ * Resolve containment that contributes an inherited Space before assignee
+ * defaults run. The REST route performs the same Project inheritance, but
+ * waiting until after the request is too late for the CLI to choose the Space
+ * lead or resolve member names safely.
+ */
+export declare function resolveTaskCreateScope(payload: TaskRecord, opts?: {
+    parentTaskCache?: Map<string, Promise<TaskRecord>>;
+    projectCache?: Map<string, Promise<TaskRecord>>;
+}): Promise<TaskCreateScopeResolution>;
+export declare function findTaskByExternalKey({ externalKey, spaceId, goalId, parentId, }: {
+    externalKey: string;
+    spaceId?: unknown;
+    goalId?: unknown;
+    parentId?: unknown;
+}): Promise<{
+    task: TaskRecord | null;
+    duplicates: TaskRecord[];
+}>;
+/**
+ * What the CLI reports under `defaultAgent` in `--json` output.
+ *
+ * The shared policy's sources (`explicit-assignee`, `caller-agent`,
+ * `caller-user`, `unassigned`) plus the three the CLI decides
+ * on its own before the policy runs: an operator-supplied `--default-agent`,
+ * inheritance from a parent, and the space lead behind `--default-agent auto`.
+ *
+ * `current-agent` was renamed to the policy's `caller-agent`: it now means
+ * "the agent this session is bound to", never "an agent we found by looking".
+ */
+export type DefaultAgentResolution = {
+    applied: boolean;
+    source: 'none' | 'explicit-assignee' | 'existing-assignee' | 'provided' | 'caller-agent' | 'caller-user' | 'unassigned' | 'parent' | 'space-lead';
+    agentIds?: string[];
+    userIds?: string[];
+    spaceId?: string;
+    /** Why nothing was assigned. An explanation for the operator, not an error. */
+    note?: string;
+};
+/**
+ * Which DEFAULTED assignees the create route will strip because they are not
+ * members of the task's space (`ASSIGNEE_NOT_IN_SPACE` degradation). Only a
+ * defaulted assignee is at risk here: an assignee the caller named explicitly
+ * is resolved against space membership up front and fails loudly, so it never
+ * reaches a `--dry-run` that "passed". A dry run that echoes such an assignee
+ * implies one the real create drops, which is what this predicts. (OSK-4857)
+ */
+export declare function droppedDefaultAssignees(resolution: DefaultAgentResolution, memberIds: ReadonlySet<string>): {
+    agentIds: string[];
+    userIds: string[];
+};
+/**
+ * Apply the shared assignee-default policy to a create payload, in place.
+ *
+ * The CLI contributes only the CLAIM — did the caller assign anyone, what
+ * executor did they declare, and which agent (if any) does this session's
+ * environment say this process is. The DECISION lives in
+ * `resolveTaskAssigneeDefaults` (`@skrr-ai/data-provider`) so `skrr`, the REST
+ * route and the `task_create` MCP tool cannot answer it differently.
+ */
+export declare function applyTaskAssigneeDefaults(payload: TaskRecord, opts?: {
+    callerUserId?: string | null;
+}): DefaultAgentResolution;
+/**
+ * An assignee field is itself an explicit choice, including an empty array.
+ * Empty arrays are the escape hatch for callers that intentionally want an
+ * unassigned task; defaulting must not turn an explicit clear into an agent
+ * assignment.
+ */
+export declare function hasExplicitTaskAssignee(payload: TaskRecord | null | undefined): boolean;
+/**
+ * Choose the implicit fallback policy for a task that has no assignee fields.
+ * Space/parent-scoped work can safely inherit the space lead (the same policy
+ * exposed by `--default-agent auto`). Personal work needs an unambiguous
+ * calling-agent identity and is resolved by the command layer.
+ */
+export declare function implicitTaskDefaultAgentMode(payload: TaskRecord, opts?: {
+    existingTask?: TaskRecord | null;
+    parentPayload?: TaskRecord;
+}): 'auto' | undefined;
+export declare function applyDefaultAgentToPayload(payload: TaskRecord, defaultAgent: unknown, opts?: {
+    parentPayload?: TaskRecord;
+    existingTask?: TaskRecord | null;
+    spaceCache?: Map<string, Promise<TaskRecord>>;
+    parentTaskCache?: Map<string, Promise<TaskRecord>>;
+    /** Implicit space defaults may leave a task unassigned when no lead exists. */
+    allowUnassignedAuto?: boolean;
+}): Promise<DefaultAgentResolution>;
+export declare function createPatchFromCreatePayload(payload: TaskRecord): TaskRecord;
+export declare function removeUndefinedFields(input: TaskRecord): TaskRecord;
+export declare function listItems(response: unknown): TaskRecord[];
+export declare function taskId(task: TaskRecord | null | undefined): string;
+export declare function taskRef(task: TaskRecord | null | undefined): string;
+export declare function formatTaskLabel(task: TaskRecord): string;
+export declare function hasTaskAssignee(task: TaskRecord | null | undefined): boolean;
+export declare function normalizeTaskUpdateEntry(entry: unknown): {
+    id: string;
+    patch: TaskRecord;
+};
+export declare function normalizeBulkUpdateInput(input: unknown): Array<{
+    id: string;
+    patch: TaskRecord;
+}>;