kanbo-cli 0.2.1 → 0.3.0

package/dist/lib/{tool-names-WfH4IURz.d.cts → approval-BsBk2xVr.d.cts}

@@ -1,4 +1,4 @@
-import { c as IssueStatus } from "./schema-D0MyXcej.cjs";
+import { c as IssueStatus, n as IssueComment, r as IssueFieldChange, t as Issue } from "./schema-D0MyXcej.cjs";
 //#region src/domain/entry-rules.d.ts
 /**
  * What a column may ask of a card before an agent puts the card in it (ruling
@@ -108,5 +108,74 @@ interface KanboToolCliEquivalent {
  */
 declare const KANBO_TOOL_CLI_EQUIVALENTS: Record<KanboToolName, KanboToolCliEquivalent>;
 //#endregion
-export { ENTRY_RULES as a, EntryRuleFacts as c, evaluateEntryRules as d, readChecklist as f, KanboToolName as i, UNMET_ENTRY_RULE_REASONS as l, serializeEntryRules as m, KANBO_TOOL_NAMES as n, ENTRY_RULE_DESCRIPTIONS as o, readEntryRules as p, KanboToolCliEquivalent as r, EntryRule as s, KANBO_TOOL_CLI_EQUIVALENTS as t, UnmetEntryRule as u };
-//# sourceMappingURL=tool-names-WfH4IURz.d.cts.map
+//#region src/domain/issue-view.d.ts
+/** An issue row with its `labels` column decoded from JSON. */
+type IssueView = Omit<Issue, 'labels'> & {
+  labels: string[];
+};
+/**
+ * Who a board change is attributed to. The `issue_field_changes.actor_kind`
+ * column owns the union; comment authors carry the same kinds plus the
+ * `system.*` markers that `normalizeCommentAuthorKind` folds away.
+ */
+type IssueActorKind = IssueFieldChange['actorKind'];
+declare function toIssueView(issue: Issue): IssueView;
+/**
+ * Fold a comment's author kind onto the actor kinds a reader renders: only a
+ * person, an agent and a provider target speak for themselves, so every
+ * `system.*` marker — whatever it marks — is the board speaking as `system`.
+ */
+declare function normalizeCommentAuthorKind(authorKind: string): IssueActorKind;
+/** Who a row is filed under, as the row stores it — what a host resolves into a name to show. */
+interface IssueActorReference {
+  kind: IssueActorKind;
+  id: string | null;
+  sourceChatSessionId: string | null;
+}
+/** What a stored row says about who wrote it: the name its writer gave, and the chat session it came from. */
+interface IssueWriterProvenance {
+  authorId: IssueComment['authorId'];
+  sourceChatSessionId: IssueComment['sourceChatSessionId'];
+}
+/**
+ * Was this row written by an outside writer?
+ *
+ * An outside writer is stored as `system`, the same kind the board writes
+ * under, so the kind alone cannot say. What a row carries can: a writer from
+ * outside — the `kanbo` command line, an agent someone ran themselves — gives
+ * a name and speaks from no chat session, while the board writing on its
+ * own behalf gives no name (`BOARD_ACTOR`) and an app's agent runtime filed under
+ * `system` always carries the session it was called in. The caller establishes
+ * the `system` kind first; this answers the rest of the question, and says in
+ * its type that such a writer has a name to show.
+ */
+declare function isOutsideWriter(provenance: IssueWriterProvenance): provenance is IssueWriterProvenance & {
+  authorId: string;
+};
+//#endregion
+//#region src/ops/approval.d.ts
+/** Where a card stands with the person who has to approve it. */
+interface BoardApproval {
+  state: 'none' | 'pending' | 'approved' | 'returned';
+  /** When the person decided, in unix seconds; `null` while nobody has. */
+  decidedAt: number | null;
+  /** What the person wrote alongside the decision, if anything. */
+  comment: string | null;
+}
+/** A card's latest comment, as a list row carries it. */
+interface CardLastComment {
+  /** Who wrote it; a person's decision (an approval, a return) is the person's. */
+  author: IssueActorKind;
+  /** Its first `LAST_COMMENT_PREVIEW_LENGTH` characters, `…` where it was cut. */
+  text: string;
+  createdAt: number;
+}
+/** What a list says beside a card whose turn is a person's, or which a person just sent back. */
+interface CardAttention {
+  /** A person sent it back and nobody has picked it up again (`BoardCardQuery.returned`). */
+  returned: boolean;
+  /** Its latest comment, for a card waiting for a person or returned; `null` for the rest. */
+  lastComment: CardLastComment | null;
+}
+//#endregion
+export { readEntryRules as C, readChecklist as S, EntryRule as _, IssueActorReference as a, UnmetEntryRule as b, isOutsideWriter as c, KANBO_TOOL_CLI_EQUIVALENTS as d, KANBO_TOOL_NAMES as f, ENTRY_RULE_DESCRIPTIONS as g, ENTRY_RULES as h, IssueActorKind as i, normalizeCommentAuthorKind as l, KanboToolName as m, CardAttention as n, IssueView as o, KanboToolCliEquivalent as p, CardLastComment as r, IssueWriterProvenance as s, BoardApproval as t, toIssueView as u, EntryRuleFacts as v, serializeEntryRules as w, evaluateEntryRules as x, UNMET_ENTRY_RULE_REASONS as y };

package/dist/lib/{tool-names-3q_GEZej.d.mts → approval-LRZ6ontC.d.mts}

@@ -1,4 +1,4 @@
-import { c as IssueStatus } from "./schema-D0MyXcej.mjs";
+import { c as IssueStatus, n as IssueComment, r as IssueFieldChange, t as Issue } from "./schema-D0MyXcej.mjs";
 //#region src/domain/entry-rules.d.ts
 /**
  * What a column may ask of a card before an agent puts the card in it (ruling
@@ -108,5 +108,74 @@ interface KanboToolCliEquivalent {
  */
 declare const KANBO_TOOL_CLI_EQUIVALENTS: Record<KanboToolName, KanboToolCliEquivalent>;
 //#endregion
-export { ENTRY_RULES as a, EntryRuleFacts as c, evaluateEntryRules as d, readChecklist as f, KanboToolName as i, UNMET_ENTRY_RULE_REASONS as l, serializeEntryRules as m, KANBO_TOOL_NAMES as n, ENTRY_RULE_DESCRIPTIONS as o, readEntryRules as p, KanboToolCliEquivalent as r, EntryRule as s, KANBO_TOOL_CLI_EQUIVALENTS as t, UnmetEntryRule as u };
-//# sourceMappingURL=tool-names-3q_GEZej.d.mts.map
+//#region src/domain/issue-view.d.ts
+/** An issue row with its `labels` column decoded from JSON. */
+type IssueView = Omit<Issue, 'labels'> & {
+  labels: string[];
+};
+/**
+ * Who a board change is attributed to. The `issue_field_changes.actor_kind`
+ * column owns the union; comment authors carry the same kinds plus the
+ * `system.*` markers that `normalizeCommentAuthorKind` folds away.
+ */
+type IssueActorKind = IssueFieldChange['actorKind'];
+declare function toIssueView(issue: Issue): IssueView;
+/**
+ * Fold a comment's author kind onto the actor kinds a reader renders: only a
+ * person, an agent and a provider target speak for themselves, so every
+ * `system.*` marker — whatever it marks — is the board speaking as `system`.
+ */
+declare function normalizeCommentAuthorKind(authorKind: string): IssueActorKind;
+/** Who a row is filed under, as the row stores it — what a host resolves into a name to show. */
+interface IssueActorReference {
+  kind: IssueActorKind;
+  id: string | null;
+  sourceChatSessionId: string | null;
+}
+/** What a stored row says about who wrote it: the name its writer gave, and the chat session it came from. */
+interface IssueWriterProvenance {
+  authorId: IssueComment['authorId'];
+  sourceChatSessionId: IssueComment['sourceChatSessionId'];
+}
+/**
+ * Was this row written by an outside writer?
+ *
+ * An outside writer is stored as `system`, the same kind the board writes
+ * under, so the kind alone cannot say. What a row carries can: a writer from
+ * outside — the `kanbo` command line, an agent someone ran themselves — gives
+ * a name and speaks from no chat session, while the board writing on its
+ * own behalf gives no name (`BOARD_ACTOR`) and an app's agent runtime filed under
+ * `system` always carries the session it was called in. The caller establishes
+ * the `system` kind first; this answers the rest of the question, and says in
+ * its type that such a writer has a name to show.
+ */
+declare function isOutsideWriter(provenance: IssueWriterProvenance): provenance is IssueWriterProvenance & {
+  authorId: string;
+};
+//#endregion
+//#region src/ops/approval.d.ts
+/** Where a card stands with the person who has to approve it. */
+interface BoardApproval {
+  state: 'none' | 'pending' | 'approved' | 'returned';
+  /** When the person decided, in unix seconds; `null` while nobody has. */
+  decidedAt: number | null;
+  /** What the person wrote alongside the decision, if anything. */
+  comment: string | null;
+}
+/** A card's latest comment, as a list row carries it. */
+interface CardLastComment {
+  /** Who wrote it; a person's decision (an approval, a return) is the person's. */
+  author: IssueActorKind;
+  /** Its first `LAST_COMMENT_PREVIEW_LENGTH` characters, `…` where it was cut. */
+  text: string;
+  createdAt: number;
+}
+/** What a list says beside a card whose turn is a person's, or which a person just sent back. */
+interface CardAttention {
+  /** A person sent it back and nobody has picked it up again (`BoardCardQuery.returned`). */
+  returned: boolean;
+  /** Its latest comment, for a card waiting for a person or returned; `null` for the rest. */
+  lastComment: CardLastComment | null;
+}
+//#endregion
+export { readEntryRules as C, readChecklist as S, EntryRule as _, IssueActorReference as a, UnmetEntryRule as b, isOutsideWriter as c, KANBO_TOOL_CLI_EQUIVALENTS as d, KANBO_TOOL_NAMES as f, ENTRY_RULE_DESCRIPTIONS as g, ENTRY_RULES as h, IssueActorKind as i, normalizeCommentAuthorKind as l, KanboToolName as m, CardAttention as n, IssueView as o, KanboToolCliEquivalent as p, CardLastComment as r, IssueWriterProvenance as s, BoardApproval as t, toIssueView as u, EntryRuleFacts as v, serializeEntryRules as w, evaluateEntryRules as x, UNMET_ENTRY_RULE_REASONS as y };

package/dist/lib/{board-store-BvWn9xTB.d.mts → board-store-D_Mpfb84.d.mts}

@@ -9,6 +9,13 @@ interface IssueStatusStore {
   /** Every status, in no particular order. */
   listAll: () => Promise<IssueStatus[]>;
   findById: (statusId: string) => Promise<IssueStatus | null>;
+  /**
+   * The status, read inside a write so no other writer can put a card in it or
+   * delete it until this transaction ends: `select … for update` on Postgres.
+   * A SQLite write already holds the whole file (`begin immediate`), so there
+   * it is `findById`.
+   */
+  lockById: (statusId: string) => Promise<IssueStatus | null>;
   /** The status, only when it belongs to the given workspace. */
   findInWorkspace: (workspaceId: string, statusId: string) => Promise<IssueStatus | null>;
   countByWorkspace: (workspaceId: string) => Promise<number>;
@@ -41,6 +48,17 @@ interface IssueRowStore {
   listAll: () => Promise<Issue[]>;
   /** Issues of one workspace, in no particular order. */
   listByWorkspace: (workspaceId: string) => Promise<Issue[]>;
+  /**
+   * The cards of one workspace a query picks, in board order, one page of them,
+   * and how many it picks in all — in one statement. The filters are conjoined;
+   * a filter left out does not narrow.
+   */
+  listPage: (query: BoardCardQuery) => Promise<BoardCardPage>;
+  /**
+   * How many cards of the workspace each milestone holds, per column — one
+   * statement, cards with no milestone left out. What a sprint list counts.
+   */
+  countByMilestone: (workspaceId: string) => Promise<BoardMilestoneCardCount[]>;
   /** Issues with the given ids, in no particular order. Missing ids are simply absent. */
   listByIds: (issueIds: string[]) => Promise<Issue[]>;
   findById: (issueId: string) => Promise<Issue | null>;
@@ -78,10 +96,66 @@ interface IssueRowStore {
   }, updatedAt: number) => Promise<number>;
   delete: (issueId: string) => Promise<void>;
 }
+/**
+ * Which cards of a workspace `listPage` reads, and which page of them.
+ *
+ * Every filter is optional and they all apply together. Text is matched
+ * ignoring case — ASCII case on SQLite, where `like` folds nothing else; every
+ * letter on Postgres (`ilike`).
+ */
+interface BoardCardQuery {
+  workspaceId: string;
+  /** Cards in any of these columns. An empty list picks nothing. */
+  statusIds?: readonly string[];
+  /** `true`: only cards waiting for a person; `false`: only cards waiting for no one. */
+  waitingForPerson?: boolean;
+  /** Only the cards directly under this card. */
+  parentIssueId?: string;
+  /** `true`: only cards with a run going on now; `false`: only cards with none. */
+  hasActiveRun?: boolean;
+  /**
+   * `true`: only cards a person sent back that nobody has picked up again —
+   * the card's latest decision (`system.approved` or `system.returned`
+   * comment, the one `readApproval` reads) is a return, it is not waiting for a
+   * person, and no run is going on on it. `false`: every other card.
+   */
+  returned?: boolean;
+  /** Cards whose key, title or description contains this text. */
+  text?: string;
+  /** Cards changed at or after this moment, in unix seconds. */
+  updatedSince?: number;
+  /** Cards carrying every one of these labels. */
+  labels?: readonly string[];
+  /** Cards of any of these priorities. An empty list picks nothing. */
+  priorities?: readonly Issue['priority'][];
+  /** How many picked cards to skip, in board order. */
+  offset?: number;
+  /** How many picked cards to return at most; every one when absent. */
+  limit?: number;
+}
+/** One page of the cards a `BoardCardQuery` picks. */
+interface BoardCardPage {
+  /** The page, in board order. */
+  cards: Issue[];
+  /** How many cards the query picks in all, before `offset` and `limit`. */
+  total: number;
+}
+/** How many cards of one milestone sit in one column. */
+interface BoardMilestoneCardCount {
+  milestoneId: string;
+  statusId: string | null;
+  count: number;
+}
 /** Comments on an issue. */
 interface IssueCommentStore {
   /** Comments of one issue, oldest first. */
   listByIssue: (issueId: string) => Promise<IssueComment[]>;
+  /**
+   * The latest comment of each of these issues — among those of `authorKinds`
+   * when given — in one statement, in no particular order. An issue with none
+   * is absent. "Latest" is the order `listByIssue` lists them in, its last.
+   */
+  listLatestByIssues: (issueIds: readonly string[], authorKinds?: readonly IssueComment['authorKind'][]) => Promise<IssueComment[]>;
   findById: (commentId: string) => Promise<IssueComment | null>;
   /**
    * The comment on that issue carrying `dedupeKey`, or `null` — one read of the
@@ -277,5 +351,4 @@ interface BoardStore {
   }) => Promise<T>;
 }
 //#endregion
-export { BoardStore as a, IssueContextRefStore as c, IssuePullRequestStore as d, IssueRelationStore as f, KanbanMetaStore as g, IssueStatusStore as h, BoardRunProjectionScope as i, IssueFieldChangeStore as l, IssueRunStore as m, BoardLinkedPullRequest as n, BoardTransactionMode as o, IssueRowStore as p, BoardRunProjection as r, IssueCommentStore as s, BoardActiveRun as t, IssueMilestoneStore as u };
-//# sourceMappingURL=board-store-BvWn9xTB.d.mts.map
+export { IssueRunStore as _, BoardMilestoneCardCount as a, BoardStore as c, IssueContextRefStore as d, IssueFieldChangeStore as f, IssueRowStore as g, IssueRelationStore as h, BoardLinkedPullRequest as i, BoardTransactionMode as l, IssuePullRequestStore as m, BoardCardPage as n, BoardRunProjection as o, IssueMilestoneStore as p, BoardCardQuery as r, BoardRunProjectionScope as s, BoardActiveRun as t, IssueCommentStore as u, IssueStatusStore as v, KanbanMetaStore as y };

package/dist/lib/{board-store-BfszzAJB.d.cts → board-store-Dx-mw2I6.d.cts}

@@ -9,6 +9,13 @@ interface IssueStatusStore {
   /** Every status, in no particular order. */
   listAll: () => Promise<IssueStatus[]>;
   findById: (statusId: string) => Promise<IssueStatus | null>;
+  /**
+   * The status, read inside a write so no other writer can put a card in it or
+   * delete it until this transaction ends: `select … for update` on Postgres.
+   * A SQLite write already holds the whole file (`begin immediate`), so there
+   * it is `findById`.
+   */
+  lockById: (statusId: string) => Promise<IssueStatus | null>;
   /** The status, only when it belongs to the given workspace. */
   findInWorkspace: (workspaceId: string, statusId: string) => Promise<IssueStatus | null>;
   countByWorkspace: (workspaceId: string) => Promise<number>;
@@ -41,6 +48,17 @@ interface IssueRowStore {
   listAll: () => Promise<Issue[]>;
   /** Issues of one workspace, in no particular order. */
   listByWorkspace: (workspaceId: string) => Promise<Issue[]>;
+  /**
+   * The cards of one workspace a query picks, in board order, one page of them,
+   * and how many it picks in all — in one statement. The filters are conjoined;
+   * a filter left out does not narrow.
+   */
+  listPage: (query: BoardCardQuery) => Promise<BoardCardPage>;
+  /**
+   * How many cards of the workspace each milestone holds, per column — one
+   * statement, cards with no milestone left out. What a sprint list counts.
+   */
+  countByMilestone: (workspaceId: string) => Promise<BoardMilestoneCardCount[]>;
   /** Issues with the given ids, in no particular order. Missing ids are simply absent. */
   listByIds: (issueIds: string[]) => Promise<Issue[]>;
   findById: (issueId: string) => Promise<Issue | null>;
@@ -78,10 +96,66 @@ interface IssueRowStore {
   }, updatedAt: number) => Promise<number>;
   delete: (issueId: string) => Promise<void>;
 }
+/**
+ * Which cards of a workspace `listPage` reads, and which page of them.
+ *
+ * Every filter is optional and they all apply together. Text is matched
+ * ignoring case — ASCII case on SQLite, where `like` folds nothing else; every
+ * letter on Postgres (`ilike`).
+ */
+interface BoardCardQuery {
+  workspaceId: string;
+  /** Cards in any of these columns. An empty list picks nothing. */
+  statusIds?: readonly string[];
+  /** `true`: only cards waiting for a person; `false`: only cards waiting for no one. */
+  waitingForPerson?: boolean;
+  /** Only the cards directly under this card. */
+  parentIssueId?: string;
+  /** `true`: only cards with a run going on now; `false`: only cards with none. */
+  hasActiveRun?: boolean;
+  /**
+   * `true`: only cards a person sent back that nobody has picked up again —
+   * the card's latest decision (`system.approved` or `system.returned`
+   * comment, the one `readApproval` reads) is a return, it is not waiting for a
+   * person, and no run is going on on it. `false`: every other card.
+   */
+  returned?: boolean;
+  /** Cards whose key, title or description contains this text. */
+  text?: string;
+  /** Cards changed at or after this moment, in unix seconds. */
+  updatedSince?: number;
+  /** Cards carrying every one of these labels. */
+  labels?: readonly string[];
+  /** Cards of any of these priorities. An empty list picks nothing. */
+  priorities?: readonly Issue['priority'][];
+  /** How many picked cards to skip, in board order. */
+  offset?: number;
+  /** How many picked cards to return at most; every one when absent. */
+  limit?: number;
+}
+/** One page of the cards a `BoardCardQuery` picks. */
+interface BoardCardPage {
+  /** The page, in board order. */
+  cards: Issue[];
+  /** How many cards the query picks in all, before `offset` and `limit`. */
+  total: number;
+}
+/** How many cards of one milestone sit in one column. */
+interface BoardMilestoneCardCount {
+  milestoneId: string;
+  statusId: string | null;
+  count: number;
+}
 /** Comments on an issue. */
 interface IssueCommentStore {
   /** Comments of one issue, oldest first. */
   listByIssue: (issueId: string) => Promise<IssueComment[]>;
+  /**
+   * The latest comment of each of these issues — among those of `authorKinds`
+   * when given — in one statement, in no particular order. An issue with none
+   * is absent. "Latest" is the order `listByIssue` lists them in, its last.
+   */
+  listLatestByIssues: (issueIds: readonly string[], authorKinds?: readonly IssueComment['authorKind'][]) => Promise<IssueComment[]>;
   findById: (commentId: string) => Promise<IssueComment | null>;
   /**
    * The comment on that issue carrying `dedupeKey`, or `null` — one read of the
@@ -277,5 +351,4 @@ interface BoardStore {
   }) => Promise<T>;
 }
 //#endregion
-export { BoardStore as a, IssueContextRefStore as c, IssuePullRequestStore as d, IssueRelationStore as f, KanbanMetaStore as g, IssueStatusStore as h, BoardRunProjectionScope as i, IssueFieldChangeStore as l, IssueRunStore as m, BoardLinkedPullRequest as n, BoardTransactionMode as o, IssueRowStore as p, BoardRunProjection as r, IssueCommentStore as s, BoardActiveRun as t, IssueMilestoneStore as u };
-//# sourceMappingURL=board-store-BfszzAJB.d.cts.map
+export { IssueRunStore as _, BoardMilestoneCardCount as a, BoardStore as c, IssueContextRefStore as d, IssueFieldChangeStore as f, IssueRowStore as g, IssueRelationStore as h, BoardLinkedPullRequest as i, BoardTransactionMode as l, IssuePullRequestStore as m, BoardCardPage as n, BoardRunProjection as o, IssueMilestoneStore as p, BoardCardQuery as r, BoardRunProjectionScope as s, BoardActiveRun as t, IssueCommentStore as u, IssueStatusStore as v, KanbanMetaStore as y };

package/dist/lib/index.cjs

@@ -1,11 +1,15 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_manifest = require("./manifest-D9nCRtXM.cjs");
-const require_migrations_path = require("./migrations-path-CZxVOgeD.cjs");
+const require_manifest = require("./manifest-QPoQl8tn.cjs");
+const require_migrations_path = require("./migrations-path-DBCE17dT.cjs");
 exports.BINDING_FILE_PATH = require_manifest.BINDING_FILE_PATH;
 exports.BOARD_ACTOR = require_manifest.BOARD_ACTOR;
 exports.BOARD_ERROR_RESPONSES = require_manifest.BOARD_ERROR_RESPONSES;
 exports.BoardError = require_migrations_path.BoardError;
 exports.CAPABILITIES_MANIFEST_VERSION = require_manifest.CAPABILITIES_MANIFEST_VERSION;
+exports.CARD_KEY_PATTERN = require_manifest.CARD_KEY_PATTERN;
+exports.COLUMN_CATALOGUE = require_manifest.COLUMN_CATALOGUE;
+exports.COLUMN_TEMPLATES = require_manifest.COLUMN_TEMPLATES;
+exports.COLUMN_TEMPLATE_IDS = require_manifest.COLUMN_TEMPLATE_IDS;
 exports.DEFAULT_BOARD_FILE_PATH = require_manifest.DEFAULT_BOARD_FILE_PATH;
 exports.DEFAULT_STATUSES = require_manifest.DEFAULT_STATUSES;
 exports.ENTRY_RULES = require_manifest.ENTRY_RULES;
@@ -31,6 +35,7 @@ exports.formatPlainActivityValue = require_manifest.formatPlainActivityValue;
 exports.ignoreBoardFile = require_manifest.ignoreBoardFile;
 exports.isEmptyActivityValue = require_manifest.isEmptyActivityValue;
 exports.isOutsideWriter = require_manifest.isOutsideWriter;
+exports.isValidCardKey = require_manifest.isValidCardKey;
 exports.maskDatabaseUrl = require_manifest.maskDatabaseUrl;
 exports.maskDatabaseUrls = require_manifest.maskDatabaseUrls;
 exports.nextIssueIdentity = require_manifest.nextIssueIdentity;
@@ -51,5 +56,6 @@ exports.readSystemCommentKind = require_manifest.readSystemCommentKind;
 exports.renderCapabilitiesMarkdown = require_manifest.renderCapabilitiesMarkdown;
 exports.runBoardWrite = require_manifest.runBoardWrite;
 exports.serializeEntryRules = require_manifest.serializeEntryRules;
+exports.suggestCardKey = require_manifest.suggestCardKey;
 exports.toIssueView = require_manifest.toIssueView;
 exports.writeBinding = require_manifest.writeBinding;