@skrr-ai/cli 0.1.8

package/dist/lib/proactiveApi.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.proactiveApi = void 0;
+/**
+ * proactiveApi.ts — request-based client for the "spawn a proactive agent"
+ * endpoints (`/api/initiatives/spawn/*`).
+ *
+ * Mirrors the `scheduleApi` / `triggerApi` pattern: these endpoints are not
+ * exposed as `dataService.*` functions, so the CLI talks to them through the
+ * shared `request` transport. Types here are a focused mirror of the server's
+ * `ProactiveAgentSpec` (api/server/services/ProactiveAgentSpec/schema.js) — only
+ * the fields the CLI reads or sends.
+ *
+ * Flow: `plan` (LLM, read-only — returns a spec draft or a clarifying message)
+ * → review → `apply` (creates the agent + installs the chosen system[s]).
+ */
+const data_provider_1 = require("@skrr-ai/data-provider");
+exports.proactiveApi = {
+    /** Plan-only: turn a sentence into a spec draft. Never writes. */
+    planProactiveAgent: (body) => data_provider_1.request.post('/api/initiatives/spawn/plan', body),
+    /** Apply a (clamped, server-re-validated) spec: create + install. */
+    applyProactiveAgentSpec: (body) => data_provider_1.request.post('/api/initiatives/spawn/apply', body),
+    /** Meta-agent path: plan and persist a reviewable recommendation. */
+    planProactiveAgentRecommendation: (body) => data_provider_1.request.post('/api/initiatives/recommendations/plan', body),
+    listProactiveAgentRecommendations: (params) => {
+        const search = new URLSearchParams();
+        if (params?.status?.length)
+            search.set('status', params.status.join(','));
+        if (params?.source)
+            search.set('source', params.source);
+        if (params?.limit)
+            search.set('limit', String(params.limit));
+        const suffix = search.toString() ? `?${search.toString()}` : '';
+        return data_provider_1.request.get(`/api/initiatives/recommendations${suffix}`);
+    },
+    approveProactiveAgentRecommendation: (recommendationId, body) => data_provider_1.request.post(`/api/initiatives/recommendations/${encodeURIComponent(recommendationId)}/approve`, body || {}),
+    applyProactiveAgentRecommendation: (recommendationId, body) => data_provider_1.request.post(`/api/initiatives/recommendations/${encodeURIComponent(recommendationId)}/apply`, body || {}),
+};

package/dist/lib/projects.d.ts

@@ -0,0 +1,293 @@
+/**
+ * Request shaping for `skrr projects` — the extensional task container inside
+ * a Space (docs/architecture/project-entity-2026-07-31.md).
+ *
+ * Following the package convention (see install-template.ts,
+ * chats-list-rooms.spec.ts), everything that decides what goes on the wire is
+ * a pure exported function tested directly, while the oclif commands own only
+ * parsing, transport, and output.
+ *
+ * Deliberately absent, per invariant P1 of the architecture doc: status,
+ * progress, planner, or DRI fields. The DONE column rendered by
+ * `toProjectListRow` is the server's live done/total projection over member
+ * tasks — never a stored field.
+ */
+export type ProjectFailure = {
+    code: string;
+    message: string;
+};
+/**
+ * Cross-space project search — `GET /api/projects`.
+ *
+ * The only project endpoint that does not take a space, and the reason it
+ * exists: everything else hangs off `/api/spaces/:spaceId/projects`, so a
+ * caller holding a project NAME had no way in. Refs are space-scoped too, so
+ * "resolve the ref first" is not an escape hatch — the space is needed to do
+ * that as well.
+ *
+ * Lives in the lib rather than `dataService` so the URL has one owner; the
+ * parity spec reads this file directly (`libPaths`).
+ */
+export interface ProjectSearchParams {
+    q?: string;
+    spaceId?: string;
+    includeArchived?: boolean;
+    limit?: number;
+}
+export interface ProjectSearchResponse {
+    object: 'list';
+    data: Array<Record<string, unknown>>;
+    has_more: boolean;
+    next_cursor: string | null;
+}
+/**
+ * Only the params that are actually set, so `withQuery` emits nothing for the
+ * rest. `includeArchived: false` is dropped rather than sent — the server reads
+ * the literal string `"true"`, so `?includeArchived=false` and omitting it mean
+ * the same thing, and sending it invites a reader to think otherwise.
+ */
+export declare function buildProjectSearchParams(params: ProjectSearchParams): Record<string, string | number | boolean | undefined>;
+/**
+ * Refuse a body that is not this endpoint's envelope.
+ *
+ * The CLI ships on its own npm cadence, so a new `skrr` against a server that
+ * predates `/api/projects` is an ordinary state — and an unmounted API path
+ * does NOT 404 here. It falls through to the SPA catch-all and returns **200
+ * with index.html**. Handed to `projectsFrom`, that HTML is an unrecognized
+ * shape, degrades to `[]`, and the command reports "No projects matching …":
+ * a missing route rendered as a truthful empty result.
+ *
+ * `projectsFrom` is right to be lenient — it absorbs two real serializations of
+ * the space-scoped list. The leniency is wrong HERE, where an unknown body can
+ * only mean the endpoint is not there, so the check lives at the boundary
+ * rather than in the shared parser.
+ */
+export declare function assertProjectSearchResponse(body: unknown): ProjectSearchResponse;
+/** The shape `GET /api/projects/:id` answers with — the project row plus the
+ *  owning-space fields the cross-space list carries. Only the two the resolver
+ *  reads are typed; the rest is the row as the server sent it. */
+export interface ProjectLookupResponse extends Record<string, unknown> {
+    id: string;
+    spaceId: string;
+}
+/**
+ * Same boundary check as `assertProjectSearchResponse`, for the same reason: a
+ * `skrr` ahead of its server hits no 404 on an unmounted path — the SPA
+ * catch-all answers 200 with index.html. Read as a project, that body has no
+ * `spaceId`, and the resolver would build `/spaces/undefined/projects/…`. The
+ * error names the remedy the caller still has on that server: `--space`.
+ */
+export declare function assertProjectLookupResponse(body: unknown): ProjectLookupResponse;
+export declare const projectApi: {
+    search: (params?: ProjectSearchParams) => Promise<ProjectSearchResponse>;
+    /**
+     * `GET /api/projects/:id` — which space owns this project, and the project
+     * itself. Canonical ids only: the server refuses a bare ref with
+     * `PROJECT_REF_REQUIRES_SPACE`, because a ref is unique only inside a space.
+     */
+    get: (projectId: string) => Promise<ProjectLookupResponse>;
+};
+export type ProjectPayloadPlan = {
+    ok: true;
+    payload: Record<string, unknown>;
+} | {
+    ok: false;
+    error: ProjectFailure;
+};
+/** Shape the POST /spaces/:id/projects body, enforcing the entity's own limits. */
+export declare function buildProjectCreatePayload(flags: {
+    title?: string;
+    description?: string;
+    icon?: string;
+    color?: string;
+    order?: number;
+    'external-key'?: string;
+}): ProjectPayloadPlan;
+/** Shape the idempotent PUT body. Upsert deliberately requires an external key. */
+export declare function buildProjectUpsertPayload(flags: Parameters<typeof buildProjectCreatePayload>[0]): ProjectPayloadPlan;
+/**
+ * Shape the PATCH body for `skrr projects update`. Empty patches are refused
+ * here (same contract as `goals update`) so a bare invocation cannot turn
+ * into a no-op request that reads as success.
+ */
+export declare function buildProjectUpdatePayload(flags: {
+    title?: string;
+    description?: string;
+    icon?: string;
+    color?: string;
+    order?: number;
+}): ProjectPayloadPlan;
+/**
+ * Extract the project rows from the list response. The data-provider types
+ * the body as `{ data: [...] }`; older/alternate serializations use
+ * `{ projects: [...] }`. Accept both so the CLI does not render "No
+ * projects." against a server that actually returned some.
+ */
+export declare function projectsFrom(response: unknown): Array<Record<string, unknown>>;
+export type ProjectListRow = {
+    ref: string;
+    title: string;
+    /** Live done/total projection over member tasks, e.g. "3/7"; "-" when absent. */
+    done: string;
+    archived: string;
+    /** The uuid. Printed because it is what every project-scoped filter accepts. */
+    id: string;
+    /** Owning space uuid — only rendered by the cross-space search. */
+    space: string;
+};
+/**
+ * One table row per project.
+ *
+ * `id` is a column and not an afterthought: `ref` (`OSK-P-12`) is space-scoped,
+ * so the commands that filter by project — `tasks list --project`,
+ * `projects tasks` — need either the uuid or a `--space` alongside the ref.
+ * Printing only the ref handed the caller the one token the next command was
+ * most likely to reject, which is the whole reason this domain felt broken.
+ *
+ * `qualify` is the cross-space form. Space-scoped, `OSK-P-12` is unambiguous
+ * and the extra prefix is noise; across spaces it is not an identifier at all —
+ * a real listing returned 8 refs of which 4 were distinct, five rows reading
+ * `OSK-P-1`. `OSK-S-3/OSK-P-1` is the smallest token that stays addressable,
+ * and it is the pair `projects show <ref> --space <ref>` already takes.
+ */
+export declare function toProjectListRow(project: Record<string, unknown>, { qualify }?: {
+    qualify?: boolean;
+}): ProjectListRow;
+/**
+ * Human rendering for `projects show`.
+ *
+ * Returns lines rather than printing, so it is testable without an oclif
+ * harness — the same split every other pure helper in this file uses.
+ *
+ * Both identifiers are printed, and that is deliberate rather than clutter:
+ * the ref is what a person reads and types back into `show`, the uuid is what
+ * `tasks list --project` accepts without also being told the space. Showing
+ * one and needing the other is the trap this command used to set.
+ */
+export declare function renderProjectShow(project: Record<string, unknown>): string[];
+/**
+ * A row on the project's Docs surface.
+ *
+ * Pages and files are ONE list with two leaf kinds, mirroring the shared
+ * `SpaceFolder` namespace the Wiki and Files tabs already sit in — so the CLI
+ * renders one table with a KIND column rather than two lists the caller has to
+ * mentally join. `id` is the token the attach/detach verbs accept, and it is a
+ * `pageId` for a page and a `file_id` for a file; splitting the column would
+ * mean the caller reads one and types the other.
+ */
+export type ProjectDocRow = {
+    kind: string;
+    id: string;
+    name: string;
+    /** `yes` for the page holding the project's brief — it is not detachable. */
+    brief: string;
+    updated: string;
+};
+/**
+ * Flatten `{ pages, files, overviewPageId }` into one ordered table.
+ *
+ * Pages come first because the brief is a page and it is the thing a caller
+ * opening a project reads first. The `overviewPageId` is marked rather than
+ * hidden: it is a real member of the surface, but detaching it would orphan
+ * the brief, so a caller needs to see which row not to touch.
+ */
+export declare function toProjectDocRows(response: unknown): ProjectDocRow[];
+/** One activity row. `actor` collapses the type/id/name triple a human reads. */
+export type ProjectActivityRow = {
+    when: string;
+    event: string;
+    entity: string;
+    actor: string;
+};
+export declare function toProjectActivityRow(item: Record<string, unknown>): ProjectActivityRow;
+/**
+ * Human lines for `projects overview`.
+ *
+ * A VIEW-only caller on a project whose brief nobody has opened yet gets
+ * `{ page: null }` — deliberately not an error (see the route). Saying so
+ * plainly matters: "no brief yet" and "you cannot see the brief" are different
+ * facts, and a bare empty output reads as the second.
+ */
+export declare function renderProjectOverview(page: Record<string, unknown> | null): string[];
+/** Human lines for `projects promote` — what moved, and where it went. */
+export declare function renderProjectPromote(result: Record<string, unknown>): string[];
+/**
+ * Resolve the `--page` / `--file` target of an attach/detach.
+ *
+ * Exactly one kind per invocation. The two endpoints are separate and take
+ * different id shapes, so accepting both in one call would mean guessing which
+ * the caller meant when only one succeeds — and a partially-applied mutation
+ * that reports success is worse than a refusal.
+ */
+export type DocTarget = {
+    ok: true;
+    kind: 'page';
+    id: string;
+} | {
+    ok: true;
+    kind: 'file';
+    id: string;
+} | {
+    ok: false;
+    error: ProjectFailure;
+};
+export declare function resolveDocTarget(flags: {
+    page?: string;
+    file?: string;
+}): DocTarget;
+/**
+ * Apply one doc association. Shared by `docs attach` and `docs detach`, which
+ * differ only in the boolean — the two endpoints, their id shapes, and the
+ * "association only, never a move" contract are identical in both directions.
+ *
+ * Returns what to call the thing in the confirmation line, since the page and
+ * file responses name it differently (`title` vs `filename`).
+ */
+export declare function setProjectDocAssociation(params: {
+    spaceId: string;
+    projectId: string;
+    target: {
+        kind: 'page' | 'file';
+        id: string;
+    };
+    attached: boolean;
+}): Promise<{
+    label: string;
+    name: string;
+}>;
+/**
+ * A project REF, as opposed to a uuid. Mirrors `PROJECT_IDENTIFIER_RE` in
+ * `api/models/Project.js` — the server tests exactly this to decide whether a
+ * value needs a space to resolve, so a caller that wants to answer "will the
+ * server need a space for this?" before sending has to agree with it.
+ */
+export declare const PROJECT_REF_PATTERN: RegExp;
+/**
+ * Is this a project id the API can resolve on its own?
+ *
+ * The distinction is what separates the two contracts: an id is globally
+ * unique, so `/tasks?projectId=` resolves it with no space at all, while a ref
+ * (`OSK-P-12`) is unique only inside its space and cannot be looked up without
+ * one. Commands whose endpoint is itself space-scoped need the space either
+ * way.
+ */
+export declare function looksLikeCanonicalProjectId(value: string): boolean;
+export declare function splitQualifiedProjectRef(value: string, spaceFlag?: string): {
+    projectRef: string;
+    spaceRef?: string;
+};
+/**
+ * Interpret `--project` on task commands. `"none"` (or `"null"`) detaches —
+ * PATCH sends `projectId: null` — anything else attaches to that project.
+ * Undefined means the flag was not passed at all.
+ */
+export declare function resolveTaskProjectFlag(value: string | undefined): string | null | undefined;
+/**
+ * The `tasks move` receipt's project clause. Names the project the way the
+ * handover receipt names an agent — human label plus id — rather than printing
+ * the raw uuid a person cannot read back. `project` is the matched row (from a
+ * space-scoped search) or undefined when it could not be resolved, in which
+ * case the id alone is printed, since the move already succeeded with it and a
+ * name lookup that failed must not make the receipt worse. (OSK-4865)
+ */
+export declare function formatProjectMoveDestination(projectId: string | null, project: Record<string, unknown> | undefined): string;