@shipbench/core 0.1.0

package/dist/layout-BS-84zwS.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Read-only surface. Consumers that only display data (e.g. Harbor's
+ * remote board mode) hold this type so the compiler prevents accidental
+ * write attempts.
+ */
+interface ReadableStorageAdapter {
+    readFile(path: string): Promise<string>;
+    readFileIfExists(path: string): Promise<string | null>;
+    listFiles(directory: string): Promise<string[]>;
+    readFiles(paths: string[]): Promise<Map<string, string>>;
+}
+/**
+ * Full read/write surface. Used by anything that mutates the `.shipbench/`
+ * directory — the CLI and in-repo agents.
+ */
+interface StorageAdapter extends ReadableStorageAdapter {
+    writeFile(path: string, content: string): Promise<void>;
+    writeFiles(files: Map<string, string>): Promise<void>;
+    deleteFile(path: string): Promise<void>;
+}
+interface ColumnDef {
+    id: string;
+    label: string;
+}
+interface PriorityConfig {
+    values: string[];
+    default: string;
+}
+/**
+ * Per-column ordered list of task slugs. Tasks present in a column's array
+ * render in that order; tasks whose slug isn't listed render below the
+ * ordered set (sub-sorted by `created` desc for stable tiebreak). The
+ * Uncategorized column ignores layout entirely.
+ */
+type BoardLayout = Record<string, string[]>;
+/**
+ * Controls how the done column is rendered. Cap is applied only when no
+ * search query is active — search always bypasses the cap so hidden matches
+ * aren't invisible.
+ */
+interface DoneDisplayConfig {
+    /**
+     * Max number of done tasks shown by default. `0` or negative disables the
+     * cap entirely (show all).
+     */
+    max: number;
+}
+interface ShipbenchConfig {
+    version: number;
+    name: string;
+    columns: ColumnDef[];
+    default_column: string;
+    done_column: string;
+    done_display: DoneDisplayConfig;
+    priority: PriorityConfig;
+    schema: {
+        custom_fields: Record<string, unknown>;
+    };
+    layout: BoardLayout;
+}
+/** A non-fatal problem encountered while resolving project configuration. */
+interface ConfigLoadWarning {
+    path: string;
+    message: string;
+}
+interface LoadConfigOptions {
+    /** Receives recoverable diagnostics without coupling core to an output stream. */
+    onWarning?: (warning: ConfigLoadWarning) => void;
+}
+interface TaskFrontmatter {
+    title: string;
+    status: string;
+    priority?: string;
+    assignee?: string;
+    tags?: string[];
+    /**
+     * Slugs of tasks that must be finished first. Data only — nothing in core
+     * gates mutations or moves a task's column based on this. An absent field
+     * and an empty array mean the same thing: no dependencies.
+     */
+    depends_on?: string[];
+    created: string;
+    updated: string;
+}
+interface TaskComment {
+    timestamp: string;
+    text: string;
+}
+interface Task {
+    slug: string;
+    frontmatter: TaskFrontmatter;
+    /** Timeless task description, excluding the reserved trailing Task Updates section. */
+    body: string;
+    /** Time-anchored entries parsed from the trailing `## Task Updates` section. */
+    comments: TaskComment[];
+}
+interface TaskValidationWarning {
+    slug: string;
+    field: string;
+    message: string;
+}
+/** Diagnostics an initialization check can surface without rejecting a project. */
+type ProjectWarning = ConfigLoadWarning | TaskValidationWarning;
+interface TaskReadResult {
+    tasks: Task[];
+    warnings: TaskValidationWarning[];
+}
+interface BoardAPI {
+    /** When true, the Board hides create/edit/drag affordances and renders a viewing experience only. */
+    readonly readOnly?: boolean;
+    getConfig(): Promise<ShipbenchConfig>;
+    listTasks(): Promise<TaskReadResult>;
+    listArchivedTasks(): Promise<TaskReadResult>;
+    createTask(title: string, fields?: Partial<TaskFrontmatter>): Promise<Task>;
+    /**
+     * Update a task's fields and/or body. When the update changes `status`, the
+     * task moves columns, so implementations also maintain layout and return the
+     * authoritative new `layout` (mirroring {@link BoardAPI.reorderTask}); `layout`
+     * is omitted when the status did not change.
+     */
+    updateTask(slug: string, fields: Partial<TaskFrontmatter>, body?: string): Promise<{
+        task: Task;
+        layout?: BoardLayout;
+    }>;
+    /** Append a time-stamped entry to the task's trailing Task Updates section. */
+    addComment(slug: string, text: string): Promise<Task>;
+    /** Edit an entry's text by zero-based index while preserving its timestamp. */
+    editComment(slug: string, index: number, text: string): Promise<Task>;
+    /** Delete an entry by zero-based index. */
+    deleteComment(slug: string, index: number): Promise<Task>;
+    moveTask(slug: string, toStatus: string): Promise<Task>;
+    /**
+     * Move (and reorder) a task. `position` is a 0-based index into the
+     * destination column's `layout` entry; `-1` means "append to end".
+     * Implementations are expected to return both the (possibly status-changed)
+     * task and the authoritative new layout so consumers can reconcile.
+     */
+    reorderTask(slug: string, toStatus: string, position: number): Promise<{
+        task: Task;
+        layout: BoardLayout;
+    }>;
+    archiveTask(slug: string, options?: {
+        force?: boolean;
+    }): Promise<void>;
+    unarchiveTask(slug: string): Promise<Task>;
+    deleteTask(slug: string): Promise<void>;
+    onTasksChanged?(callback: () => void): () => void;
+    /**
+     * Turn a repo-root-relative path (e.g. `docs/spec.md`) into a URL the host can
+     * actually serve, so Markdown links to repo files in a task body resolve to
+     * something real. Return `null` when the path has no reachable destination.
+     *
+     * Optional, like {@link BoardAPI.onTasksChanged}: hosts that cannot point at
+     * repo files omit it, and the Board renders those links as plain, visible
+     * paths rather than dead anchors.
+     */
+    resolveRepoLink?(repoRelativePath: string): string | null;
+}
+
+/**
+ * Pure layout algebra — the single definition of manual task ordering.
+ *
+ * `layout.json` is machine-managed, and for a while two implementations of these
+ * rules existed: core's (authoritative, applied on write) and the Board store's
+ * optimistic copy, kept in sync by hand and by comment. They had already begun
+ * to diverge. Both now call these functions, so there is no mirror left to
+ * drift — see docs/audits/board-move-algorithm-audit.md.
+ *
+ * Nothing here does I/O. Callers supply the current layout and the task list.
+ */
+/**
+ * `created` desc — the deterministic fallback order for unpositioned tasks.
+ * Newest first, because rendering an unordered column is most useful with the
+ * freshest work on top. `compareTaskReadiness` in `availability.ts` breaks its
+ * `created` tie the other way; the two serve different questions and are not
+ * expected to agree.
+ */
+declare function byCreatedDesc(a: Task, b: Task): number;
+/** `updated` desc — how the done column always sorts. */
+declare function byUpdatedDesc(a: Task, b: Task): number;
+/**
+ * Drop a slug from every column.
+ *
+ * When `existingSlugs` is given, slugs whose task no longer exists are pruned
+ * too, which is how a stale `layout.json` heals over time. Omit it to touch
+ * nothing but `slug` — rollback paths want that, since they are restoring state
+ * rather than reconciling it.
+ */
+declare function layoutWithoutTask(layout: BoardLayout, slug: string, existingSlugs?: ReadonlySet<string>): BoardLayout;
+/**
+ * The layout after moving `slug` into `toStatus` at `position`.
+ *
+ * `position` is a 0-based index; `-1` (or past the end) appends. It is computed
+ * by callers against the *visible* column — layout order followed by
+ * unpositioned tasks in `created` desc order — so this materializes those
+ * leftovers into the column array before splicing, keeping the layout a superset
+ * of what the user is looking at. Without that step a position computed on
+ * screen would land somewhere else in the file.
+ *
+ * The done column never carries manual order: it time-sorts by `updated`, so its
+ * key is dropped entirely.
+ */
+declare function layoutAfterMove({ layout, tasks, slug, toStatus, position, doneColumn, }: {
+    layout: BoardLayout;
+    /** Every live task. Used for leftovers and for pruning stale slugs. */
+    tasks: Task[];
+    slug: string;
+    toStatus: string;
+    position: number;
+    doneColumn: string;
+}): BoardLayout;
+/**
+ * The tasks belonging to one column, in render order.
+ *
+ * - Regular column: `layout[columnId]` order first, then tasks with that status
+ *   and no layout entry, `created` desc.
+ * - Done column (`columnId === doneColumn`): layout ignored, `updated` desc.
+ *   Manual ordering stops meaning anything once work is finished.
+ * - Uncategorized (any `columnId` not in `validStatuses`): every task whose
+ *   status matches no column, `created` desc. Layout ignored.
+ *
+ * `doneColumn` is deliberately required. It was optional, and `DetailView`
+ * omitted it — so keyboard navigation through the done column ran in a different
+ * order than the column being looked at.
+ */
+declare function orderedTasksForColumn(tasks: Task[], layout: BoardLayout | undefined, columnId: string, validStatuses: ReadonlySet<string>, doneColumn: string): Task[];
+
+export { type BoardLayout as B, type ColumnDef as C, type DoneDisplayConfig as D, type LoadConfigOptions as L, type ProjectWarning as P, type ReadableStorageAdapter as R, type StorageAdapter as S, type Task as T, type ShipbenchConfig as a, type TaskFrontmatter as b, type TaskReadResult as c, type BoardAPI as d, type ConfigLoadWarning as e, type PriorityConfig as f, type TaskComment as g, type TaskValidationWarning as h, byCreatedDesc as i, byUpdatedDesc as j, layoutWithoutTask as k, layoutAfterMove as l, orderedTasksForColumn as o };

package/dist/layout.d.ts

@@ -0,0 +1 @@
+export { i as byCreatedDesc, j as byUpdatedDesc, l as layoutAfterMove, k as layoutWithoutTask, o as orderedTasksForColumn } from './layout-BS-84zwS.js';

package/dist/layout.js

@@ -0,0 +1,14 @@
+import {
+  byCreatedDesc,
+  byUpdatedDesc,
+  layoutAfterMove,
+  layoutWithoutTask,
+  orderedTasksForColumn
+} from "./chunk-7T2E4KSJ.js";
+export {
+  byCreatedDesc,
+  byUpdatedDesc,
+  layoutAfterMove,
+  layoutWithoutTask,
+  orderedTasksForColumn
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@shipbench/core",
+  "version": "0.1.0",
+  "description": "Headless library for the ShipBench project convention — parse, validate, and write Markdown task files through a pluggable storage adapter.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gmmurray/shipbench.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://shipbench.dev",
+  "bugs": {
+    "url": "https://github.com/gmmurray/shipbench/issues"
+  },
+  "keywords": [
+    "shipbench",
+    "project-management",
+    "tasks",
+    "kanban",
+    "markdown",
+    "frontmatter",
+    "git",
+    "agents"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./layout": {
+      "types": "./dist/layout.d.ts",
+      "import": "./dist/layout.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/layout.ts --format esm --dts",
+    "dev": "tsup src/index.ts src/layout.ts --format esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}