@hasna/todos 0.15.52 → 0.16.0

package/dist/sdk/resolve.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Credential and authority resolution for the `@hasna/todos/sdk` surface.
+ *
+ * There is exactly ONE resolver on the fleet — the client chain in
+ * `@hasna/contracts/client` — and this module is the SDK's adapter onto it
+ * (2026-09-04 adoption ruling, hasna/apps#1720). The SDK used to carry its own
+ * chain: `TODOS_URL` for the authority and an unprefixed key name (or an `apiKey` field
+ * inside `~/.todos/config.json`) for the credential. Both are gone. A credential
+ * in `config.json` was a world-readable secret in a file the CLI also rewrites
+ * for unrelated settings, and the unprefixed names shadowed the canonical
+ * `HASNA_TODOS_API_URL` / `HASNA_TODOS_API_KEY` pair — an operator who exported
+ * the canonical pair got the localhost default anyway.
+ *
+ * The tiers are the fleet's five, resolved fresh on every call:
+ *
+ *   1. an explicit argument      — `options.apiKey` / `options.baseUrl`
+ *   2. a deliberate env pointer  — `HASNA_TODOS_API_KEY_OVERRIDE`, `HASNA_PROFILE`,
+ *                                  `HASNA_TODOS_API_KEY_REF`
+ *   3. the macOS Keychain        — `hasna.credentials.todos.api-key`
+ *   4. disk                      — `~/.hasna/todos/config/credentials` (0400/0600)
+ *   5. `HASNA_TODOS_API_KEY`     — a legitimate tier, no deprecation notice
+ *
+ * with the authority following `HASNA_TODOS_API_URL`, the Keychain `api-url`
+ * item, the credentials file, and finally the fleet gateway
+ * `https://api.hasna.com/todos`. The legacy unprefixed `TODOS_*` spellings
+ * remain only as the resolver's silent alias fallback for one release.
+ *
+ * LOCAL MODE IS DELIBERATE, NEVER A FALLBACK FROM FAILURE. `TodosClient` speaks
+ * the `/api/*` plane that `todos-serve` exposes on a workstation, so the
+ * unhosted default — `http://localhost:19427`, no credential — is a real
+ * product mode rather than a silent degradation. It is therefore reachable in
+ * exactly two ways: the deliberate opt-in `HASNA_TODOS_LOCAL=1`, or an
+ * environment where NOTHING resolves at all. A credential that resolves but
+ * cannot be used, an unreadable credential file, an authority that is set but
+ * malformed — every one of those THROWS. And when local mode is selected the
+ * SDK says so, once per process, on stderr: a client silently talking to an
+ * empty local store while the operator believes it is on the fleet is the
+ * false-green this whole ruling exists to end.
+ */
+import { type CredentialChainOptions } from "@hasna/contracts/client";
+import { TodosV1Client, type TodosV1ClientOptions } from "./v1.generated.js";
+/** The unhosted `todos-serve` a workstation runs. Never a hosted authority. */
+export declare const TODOS_LOCAL_SERVE_URL = "http://localhost:19427";
+type Env = Record<string, string | undefined>;
+export interface TodosSdkTransport {
+    /** `"http"` for a resolved hosted authority, `"local-serve"` for the unhosted default. */
+    mode: "http" | "local-serve";
+    /**
+     * Origin (plus any gateway path prefix) WITHOUT the `/v1` suffix, so a caller
+     * that composes `/api/...` or `/v1/...` gets exactly one version segment.
+     */
+    baseUrl: string;
+    /** The credential, or null in local mode. */
+    apiKey: string | null;
+    /** WHERE the credential came from — an env key NAME, a Keychain reference, a path. Never a value. */
+    apiKeySource: string | null;
+    /** WHERE the authority came from, or `"local-serve"`. */
+    apiUrlSource: string;
+}
+export interface ResolveTodosSdkTransportOptions {
+    /** Tier 1: an explicit authority. Used verbatim, minus a trailing slash. */
+    baseUrl?: string | undefined;
+    /** Tier 1: an explicit credential. */
+    apiKey?: string | undefined;
+    /** Tier 1 profile selection and the injectable `security` runner tests use. */
+    credentials?: CredentialChainOptions;
+    /** Defaults to `process.env`. */
+    env?: Env;
+    /** Where the one-line local-mode notice goes. Defaults to `process.stderr`. */
+    notice?: (line: string) => void;
+}
+/** Reset the once-per-process local-mode notice. Test seam only. */
+export declare function __resetTodosSdkLocalNotice(): void;
+/**
+ * Resolve the SDK's authority and credential. Explicit arguments win; otherwise
+ * the @hasna/contracts chain decides, and only a fully unconfigured environment
+ * (or the deliberate opt-in) lands on the local serve.
+ */
+export declare function resolveTodosSdkTransport(options?: ResolveTodosSdkTransportOptions): TodosSdkTransport;
+/**
+ * Build the hosted `/v1` client with the fleet resolver behind it — the
+ * generated {@link TodosV1Client} takes an explicit `baseUrl` and has no
+ * environment surface of its own, which left every caller writing a private
+ * copy of the chain.
+ *
+ * Throws when no credential resolves: this client speaks only to the hosted
+ * authority, so there is no local mode to degrade to.
+ */
+export declare function createTodosV1Client(options?: ResolveTodosSdkTransportOptions & Pick<TodosV1ClientOptions, "fetch" | "headers">): TodosV1Client;
+export {};
+//# sourceMappingURL=resolve.d.ts.map

package/dist/sdk/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/sdk/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,EAKL,KAAK,sBAAsB,EAE5B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAG7E,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,2BAA2B,CAAC;AAE9D,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAE9C,MAAM,WAAW,iBAAiB;IAChC,0FAA0F;IAC1F,IAAI,EAAE,MAAM,GAAG,aAAa,CAAC;IAC7B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,qGAAqG;IACrG,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,+BAA+B;IAC9C,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,+EAA+E;IAC/E,WAAW,CAAC,EAAE,sBAAsB,CAAC;IACrC,iCAAiC;IACjC,GAAG,CAAC,EAAE,GAAG,CAAC;IACV,+EAA+E;IAC/E,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAID,oEAAoE;AACpE,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD;AAiBD;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,+BAAoC,GAC5C,iBAAiB,CA+FnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,+BAA+B,GAAG,IAAI,CAAC,oBAAoB,EAAE,OAAO,GAAG,SAAS,CAAM,GAC9F,aAAa,CAmDf"}

package/dist/sdk/v1.generated.d.ts

@@ -1,3 +1,19 @@
+export interface MachineAuthority {
+    "tenant_id": string;
+    "kid": string;
+}
+export interface Machine {
+    "id": string;
+    "name": string;
+    "hostname": string;
+    "platform": string;
+    "last_seen_at": string;
+    "metadata": Record<string, unknown>;
+    "created_at": string;
+    "ssh_address": string;
+    "is_primary": boolean;
+    "archived_at": string;
+}
 export interface Task {
     "id"?: string;
     "title"?: string;
@@ -18,6 +34,9 @@ export interface Task {
     "updated_at"?: string;
 }
 export interface Project {
+    "status"?: "active" | "completed" | "on_hold" | "archived";
+    "short_id"?: string | null;
+    "metadata"?: Record<string, unknown>;
     "id"?: string;
     "name"?: string;
     "path"?: string;
@@ -412,6 +431,7 @@ export interface ProjectResourcePage {
     "truncated": false;
 }
 export interface TaskList {
+    "status"?: "active" | "completed" | "archived";
     "id"?: string;
     "project_id"?: string | null;
     "slug"?: string;
@@ -500,7 +520,9 @@ export interface Plan {
     "agent_id"?: string | null;
     "name": string;
     "description"?: string | null;
-    "status": "active" | "completed" | "archived";
+    "start_date"?: string | null;
+    "end_date"?: string | null;
+    "status": "active" | "completed" | "archived" | "planning" | "cancelled";
     "created_at": string;
     "updated_at": string;
 }
@@ -634,6 +656,9 @@ export interface TaskFailureResult {
     "retryTask"?: Task;
 }
 export interface CreateProjectInput {
+    "status"?: "active" | "completed" | "on_hold" | "archived";
+    "short_id"?: string | null;
+    "metadata"?: Record<string, unknown>;
     "name": string;
     "path": string;
     "description"?: string;
@@ -642,6 +667,9 @@ export interface CreateProjectInput {
     "parent_id"?: string;
 }
 export interface UpdateProjectInput {
+    "status"?: "active" | "completed" | "on_hold" | "archived";
+    "short_id"?: string | null;
+    "metadata"?: Record<string, unknown>;
     "name"?: string;
     "path"?: string;
     "description"?: string | null;
@@ -670,12 +698,21 @@ export interface PlanProjectLinkRollbackInput {
     "receipt_id": string;
     "expected_plan_revision": string;
 }
+export interface PlanProjectLinkConflictResponse {
+    "error": string;
+    "code"?: string;
+    "conflict"?: boolean;
+    "operation_committed"?: true;
+    "current_state_matches_receipt"?: false;
+    "receipt"?: PlanProjectLinkReceipt;
+}
 export interface ErrorResponse {
     "error": string;
     "code"?: string;
     "conflict"?: boolean;
 }
 export interface CreateTaskListInput {
+    "status"?: "active" | "completed" | "archived";
     "name": string;
     "slug"?: string;
     "project_id"?: string;
@@ -683,6 +720,7 @@ export interface CreateTaskListInput {
     "metadata"?: Record<string, unknown>;
 }
 export interface UpdateTaskListInput {
+    "status"?: "active" | "completed" | "archived";
     "slug"?: string;
     "name"?: string;
     "description"?: string;
@@ -703,7 +741,9 @@ export interface CreatePlanInput {
     "project_id"?: string;
     "task_list_id"?: string;
     "agent_id"?: string;
-    "status"?: "active" | "completed" | "archived";
+    "start_date"?: string | null;
+    "end_date"?: string | null;
+    "status"?: "active" | "completed" | "archived" | "planning" | "cancelled";
 }
 export interface UpdatePlanInput {
     "name"?: string;
@@ -711,7 +751,9 @@ export interface UpdatePlanInput {
     "description"?: string;
     "task_list_id"?: string;
     "agent_id"?: string;
-    "status"?: "active" | "completed" | "archived";
+    "start_date"?: string | null;
+    "end_date"?: string | null;
+    "status"?: "active" | "completed" | "archived" | "planning" | "cancelled";
 }
 export interface CreateTemplateInput {
     "name": string;
@@ -726,6 +768,7 @@ export interface CreateTemplateInput {
     "tasks"?: Array<CreateTemplateTaskInput>;
 }
 export interface UpdateTemplateInput {
+    "expected_version"?: number;
     "name"?: string;
     "title_pattern"?: string;
     "description"?: string | null;
@@ -1037,6 +1080,8 @@ export declare class TodosV1Client {
         "tasks"?: Array<Task>;
         "projects"?: Array<Project>;
         "projectMachinePaths"?: Array<Record<string, unknown>>;
+        "machines"?: Array<Machine>;
+        "expected_machine_authority"?: MachineAuthority;
         "plans"?: Array<Record<string, unknown>>;
         "agents"?: Array<Record<string, unknown>>;
         "taskLists"?: Array<Record<string, unknown>>;
@@ -1051,6 +1096,7 @@ export declare class TodosV1Client {
         }>;
     }, init?: RequestInit): Promise<{
         "received"?: number;
+        "machine_authority"?: MachineAuthority;
         "result"?: {
             "inserted"?: number;
             "updated"?: number;
@@ -1066,6 +1112,29 @@ export declare class TodosV1Client {
             "applied": boolean;
         }>;
     }>;
+    /** Read the complete shared machine registry */
+    listMachines(init?: RequestInit): Promise<{
+        "authority": MachineAuthority;
+        "schema_version": 2;
+        "machines": Array<Machine>;
+    }>;
+    /** Apply an atomic machine registry operation */
+    mutateMachineRegistry(body: {
+        "expected_authority": MachineAuthority;
+        "action": "register" | "heartbeat" | "set-primary" | "archive" | "unarchive" | "delete" | "import";
+        "name"?: string;
+        "id"?: string;
+        "options"?: Record<string, unknown>;
+        "machines"?: Array<Machine>;
+    }, init?: RequestInit): Promise<{
+        "authority": MachineAuthority;
+        "schema_version": 2;
+        "machines": Array<Machine>;
+        "machine"?: Machine;
+        "inserted": number;
+        "skipped": number;
+        "deleted"?: boolean;
+    }>;
     /** List plans */
     listPlans(query?: {
         "project_id"?: string;
@@ -1090,6 +1159,39 @@ export declare class TodosV1Client {
     updatePlan(id: string, body: UpdatePlanInput, init?: RequestInit): Promise<{
         "plan"?: Plan;
     }>;
+    /** Read complete plan comment history */
+    listPlanComments(id: string, query?: {
+        "plan_read_contract"?: "1";
+    }, init?: RequestInit): Promise<{
+        "count": number;
+        "comments": Array<{
+            "id": string;
+            "plan_id": string;
+            "content": string;
+            "created_at": string;
+            "agent_id": string | null;
+            "session_id": string | null;
+            "type": "comment" | "progress" | "note";
+            "progress_pct": number | null;
+        }>;
+        "history_selection"?: {
+            "schema_version": 1;
+            "plan_id": string;
+            "complete": true;
+        };
+    }>;
+    /** Delete a plan, detaching linked records only with force and preserving their content/history */
+    deletePlanPreserving(id: string, body: {
+        "force"?: boolean;
+    }, init?: RequestInit): Promise<{
+        "schema_version": 1;
+        "plan_id": string;
+        "deleted": boolean;
+        "detached_task_ids": Array<string>;
+        "detached_task_list_ids": Array<string>;
+        "detached_tasks": number;
+        "detached_task_lists": number;
+    }>;
     /** Plan atomic linkage of an existing plan and every current member task to a project */
     planPlanProjectLink(id: string, query?: {
         "project_id": string;
@@ -1111,6 +1213,50 @@ export declare class TodosV1Client {
     appendPrGroupEvent(id: string, body: AppendPrGroupEventInput, init?: RequestInit): Promise<PrGroupMutationResult>;
     /** Fence the prior attempt and create or adopt a recovery generation */
     recoverPrGroup(id: string, body: RecoverPrGroupInput, init?: RequestInit): Promise<PrGroupMutationResult>;
+    /** Inspect bounded atomic migration authority (explicit todos:migrate scope required) */
+    getAtomicProjectMigrationCapability(init?: RequestInit): Promise<{
+        "schema_version": 1;
+        "authority": {
+            "tenant_id": string;
+            "kid": string;
+            "deployment_id": string;
+        };
+        "supported_families": Array<string>;
+        "supported_tombstones": Array<string>;
+        "max_records": number;
+        "max_bytes": number;
+        "atomic": true;
+    }>;
+    /** Atomically reconcile a bounded project snapshot with durable replay receipts */
+    importAtomicProjectSnapshot(body: {
+        "schema_version": 1;
+        "operation_id": string;
+        "expected_authority": {
+            "tenant_id": string;
+            "kid": string;
+            "deployment_id": string;
+        };
+        "snapshot_hash": string;
+        "snapshot": Record<string, unknown>;
+    }, init?: RequestInit): Promise<{
+        "schema_version": 1;
+        "operation_id": string;
+        "snapshot_hash": string;
+        "authority": {
+            "tenant_id": string;
+            "kid": string;
+            "deployment_id": string;
+        };
+        "status": "complete";
+        "records": Array<{
+            "object_type": string;
+            "object_id": string;
+            "outcome": "inserted" | "updated" | "identical" | "superseded" | "deleted" | "detached";
+            "before_hash": string | null;
+            "after_hash": string;
+            "source_hash": string;
+        }>;
+    }>;
     /** Read the live package-owned Projects to Todos registration capability */
     getProjectRegistrationCapability(init?: RequestInit): Promise<{
         "capability": ProjectRegistrationCapability;
@@ -1196,6 +1342,19 @@ export declare class TodosV1Client {
     updateProject(id: string, body: UpdateProjectInput, init?: RequestInit): Promise<{
         "project"?: Project;
     }>;
+    /** Delete project identity and atomically detach linked records without deleting their content */
+    deleteProjectPreserving(id: string, body: {
+        "force"?: boolean;
+        "require_completed_tasks"?: boolean;
+    }, init?: RequestInit): Promise<{
+        "schema_version": 1;
+        "project_id": string;
+        "deleted": boolean;
+        "preserved_tasks": number;
+        "preserved_plans": number;
+        "detached_task_lists": number;
+        "detached_child_projects": number;
+    }>;
     /** Atomically rename a project and its canonical task list */
     renameProject(id: string, body: RenameProjectInput, init?: RequestInit): Promise<{
         "project"?: Project;
@@ -1241,6 +1400,18 @@ export declare class TodosV1Client {
     updateTaskList(id: string, body: UpdateTaskListInput, init?: RequestInit): Promise<{
         "task_list"?: TaskList;
     }>;
+    /** Delete a task list, optionally detaching linked tasks and plans while retaining their content and history */
+    deleteTaskListPreserving(id: string, body: {
+        "force"?: boolean;
+    }, init?: RequestInit): Promise<{
+        "schema_version": 1;
+        "task_list_id": string;
+        "deleted": boolean;
+        "detached_task_ids": Array<string>;
+        "detached_plan_ids": Array<string>;
+        "detached_tasks": number;
+        "detached_plans": number;
+    }>;
     /** Apply one exact task-manifest graph through the Todos authority */
     applyTaskManifest(body: TaskManifest, init?: RequestInit): Promise<TaskManifestApplyResponse>;
     /** Recover one exact task-manifest apply receipt from its managed plan id */
@@ -1278,6 +1449,8 @@ export declare class TodosV1Client {
         "project_id"?: string;
         "parent_id"?: string | null;
         "include_subtasks"?: boolean;
+        "include_archived"?: boolean;
+        "plan_read_contract"?: "1";
         "plan_id"?: string;
         "task_list_id"?: string;
         "assigned_to"?: string;
@@ -1290,6 +1463,12 @@ export declare class TodosV1Client {
         "tasks": Array<Task>;
         "count": number;
         "total": number;
+        "selection"?: {
+            "schema_version": 1;
+            "plan_id": string;
+            "include_subtasks": true;
+            "include_archived": boolean;
+        };
     }>;
     /** Create a task */
     createTask(body: CreateTaskInput, init?: RequestInit): Promise<{
@@ -1364,6 +1543,19 @@ export declare class TodosV1Client {
     createTemplate(body: CreateTemplateInput, init?: RequestInit): Promise<{
         "template"?: Template;
     }>;
+    /** Atomically initialize server-owned bundled definitions, retaining existing same-name templates */
+    initializeTemplates(body: Record<string, unknown>, init?: RequestInit): Promise<{
+        "schema_version": 1;
+        "created": number;
+        "skipped": number;
+        "names": Array<string>;
+        "records": Array<{
+            "definition_index": number;
+            "ids": Array<string>;
+            "name": string;
+            "status": "created" | "skipped";
+        }>;
+    }>;
     /** Get one reusable task template with its checklist steps */
     getTemplate(id: string, init?: RequestInit): Promise<{
         "template"?: Template;
@@ -1376,6 +1568,30 @@ export declare class TodosV1Client {
     /** Update reusable template metadata and defaults */
     updateTemplate(id: string, body: UpdateTemplateInput, init?: RequestInit): Promise<{
         "template"?: Template;
+        "history_write"?: {
+            "schema_version": 1;
+            "template_id": string;
+            "previous_version": number;
+            "version": number;
+            "recorded": true;
+        };
+    }>;
+    /** Read recorded template versions with explicit missing-version evidence */
+    getTemplateHistory(id: string, init?: RequestInit): Promise<{
+        "current_version": number;
+        "versions": Array<{
+            "id": string;
+            "template_id": string;
+            "version": number;
+            "snapshot": string;
+            "created_at": string;
+        }>;
+        "selection": {
+            "schema_version": 1;
+            "template_id": string;
+            "complete": boolean;
+            "missing_versions": Array<number>;
+        };
     }>;
 }
 //# sourceMappingURL=v1.generated.d.ts.map