@shipbench/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gmmurray
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# @shipbench/core
+
+The headless library behind [ShipBench](https://github.com/gmmurray/shipbench) —
+Git-native project management where the task board lives in the repository as
+plain Markdown.
+
+This package parses, validates, and writes that board. It has **no filesystem
+access, no UI, and no network calls of its own**: every read and write goes
+through a `StorageAdapter` you supply, so the same logic runs against a local
+checkout, the GitHub API, or an in-memory fixture in a test.
+
+Most people want the [`shipbench` CLI](https://www.npmjs.com/package/shipbench)
+instead. Use this package when you are building a tool on top of the
+convention.
+
+## Install
+
+```bash
+npm install @shipbench/core
+```
+
+## Usage
+
+```ts
+import { FsAdapter, loadConfig, listTasks, createTask } from '@shipbench/core';
+
+const adapter = new FsAdapter(process.cwd());
+const config = await loadConfig(adapter);
+
+const { tasks, warnings } = await listTasks(adapter, config);
+
+await createTask(adapter, config, {
+  title: 'Build the API',
+  priority: 'high',
+  tags: ['backend'],
+});
+```
+
+## Adapters
+
+Two implementations ship with the package:
+
+- **`FsAdapter`** — full read/write against the local filesystem.
+- **`GitHubAdapter`** — reads `.shipbench/` through the GitHub Contents API.
+  Cross-runtime, so it works in Node, browsers, and Cloudflare Workers.
+
+The interface is deliberately small so additional hosts stay easy to add:
+
+```ts
+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>>;
+}
+
+interface StorageAdapter extends ReadableStorageAdapter {
+  writeFile(path: string, content: string): Promise<void>;
+  writeFiles(files: Map<string, string>): Promise<void>;
+  deleteFile(path: string): Promise<void>;
+}
+```
+
+Consumers that only display data should hold a `ReadableStorageAdapter` — it
+turns an accidental write into a compile error.
+
+## What it gives you
+
+- **Tasks** — `createTask`, `getTask`, `updateTask`, `moveTask`, `reorderTask`,
+  `deleteTask`, `listTasks`, `searchTasks`
+- **Archiving** — `archiveTask`, `unarchiveTask`, `listArchivedTasks`
+- **Dependencies** — `listAvailableTasks`, `listBlockedTasks`,
+  `buildTaskDependencyGraph`
+- **Comments** — `addComment`, `editComment`, `deleteComment`
+- **Config and setup** — `loadConfig`, `validateConfig`, `initProject`,
+  `DEFAULT_CONFIG`
+- **Slugs** — `slugify`, `resolveSlugCollision`
+
+## Design rules worth knowing
+
+**Strict on write, graceful on read.** Invalid statuses and priorities are
+rejected on write. On read, a task with an unrecognized status comes back with a
+validation warning rather than being dropped — the board never silently loses
+work.
+
+**Unknown frontmatter is preserved.** Core passes through fields it does not own,
+with a warning. It never strips data it did not write.
+
+**Timestamps are managed for you.** `created` is set once; `updated` moves on
+every mutation. Both ISO 8601.
+
+**Partial configs are fine.** `config.json` is deep-merged over `DEFAULT_CONFIG`
+at read time, so any field can be omitted.
+
+## The `/layout` subpath
+
+Manual task ordering is shared contract, not private logic — hosts running
+optimistic updates must produce the same order core would write. It is exported
+from a pure subpath that imports only types:
+
+```ts
+import { orderedTasksForColumn, layoutAfterMove } from '@shipbench/core/layout';
+```
+
+Import ordering helpers from `@shipbench/core/layout`, never the package root —
+the root re-exports `FsAdapter`, which pulls in `node:fs` and will break a
+browser bundle.
+
+## License
+
+MIT

package/dist/chunk-7T2E4KSJ.js

@@ -0,0 +1,68 @@
+// src/layout.ts
+function byCreatedDesc(a, b) {
+  return Date.parse(b.frontmatter.created) - Date.parse(a.frontmatter.created);
+}
+function byUpdatedDesc(a, b) {
+  return Date.parse(b.frontmatter.updated) - Date.parse(a.frontmatter.updated);
+}
+function layoutWithoutTask(layout, slug, existingSlugs) {
+  const next = {};
+  for (const [columnId, slugs] of Object.entries(layout)) {
+    next[columnId] = slugs.filter(
+      (candidate) => candidate !== slug && (existingSlugs === void 0 || existingSlugs.has(candidate))
+    );
+  }
+  return next;
+}
+function layoutAfterMove({
+  layout,
+  tasks,
+  slug,
+  toStatus,
+  position,
+  doneColumn
+}) {
+  const existingSlugs = new Set(tasks.map((task) => task.slug));
+  const next = layoutWithoutTask(layout, slug, existingSlugs);
+  delete next[doneColumn];
+  if (toStatus === doneColumn) return next;
+  const currentOrder = next[toStatus] ?? [];
+  const placed = new Set(currentOrder);
+  const leftovers = tasks.filter(
+    (task) => task.frontmatter.status === toStatus && task.slug !== slug && !placed.has(task.slug)
+  ).slice().sort(byCreatedDesc).map((task) => task.slug);
+  const destination = [...currentOrder, ...leftovers];
+  const insertAt = position < 0 || position > destination.length ? destination.length : position;
+  destination.splice(insertAt, 0, slug);
+  next[toStatus] = destination;
+  return next;
+}
+function orderedTasksForColumn(tasks, layout, columnId, validStatuses, doneColumn) {
+  if (!validStatuses.has(columnId)) {
+    return tasks.filter((task) => !validStatuses.has(task.frontmatter.status)).slice().sort(byCreatedDesc);
+  }
+  if (columnId === doneColumn) {
+    return tasks.filter((task) => task.frontmatter.status === columnId).slice().sort(byUpdatedDesc);
+  }
+  const inColumn = tasks.filter((task) => task.frontmatter.status === columnId);
+  const bySlug = new Map(inColumn.map((task) => [task.slug, task]));
+  const ordered = [];
+  const placed = /* @__PURE__ */ new Set();
+  for (const slug of layout?.[columnId] ?? []) {
+    const task = bySlug.get(slug);
+    if (task) {
+      ordered.push(task);
+      placed.add(slug);
+    }
+  }
+  const leftovers = inColumn.filter((task) => !placed.has(task.slug)).slice().sort(byCreatedDesc);
+  return [...ordered, ...leftovers];
+}
+
+export {
+  byCreatedDesc,
+  byUpdatedDesc,
+  layoutWithoutTask,
+  layoutAfterMove,
+  orderedTasksForColumn
+};

package/dist/index.d.ts

@@ -0,0 +1,252 @@
+import { S as StorageAdapter, R as ReadableStorageAdapter, T as Task, a as ShipbenchConfig, L as LoadConfigOptions, P as ProjectWarning, b as TaskFrontmatter, c as TaskReadResult, B as BoardLayout } from './layout-BS-84zwS.js';
+export { d as BoardAPI, C as ColumnDef, e as ConfigLoadWarning, D as DoneDisplayConfig, f as PriorityConfig, g as TaskComment, h as TaskValidationWarning, i as byCreatedDesc, j as byUpdatedDesc, l as layoutAfterMove, k as layoutWithoutTask, o as orderedTasksForColumn } from './layout-BS-84zwS.js';
+
+declare class FsAdapter implements StorageAdapter {
+    private rootDir;
+    constructor(rootDir: string);
+    private resolve;
+    readFile(path: string): Promise<string>;
+    readFileIfExists(path: string): Promise<string | null>;
+    writeFile(path: string, content: string): Promise<void>;
+    deleteFile(path: string): Promise<void>;
+    listFiles(directory: string): Promise<string[]>;
+    readFiles(paths: string[]): Promise<Map<string, string>>;
+    writeFiles(files: Map<string, string>): Promise<void>;
+}
+
+interface GitHubAdapterOptions {
+    owner: string;
+    repo: string;
+    token: string;
+    branch?: string;
+    /** Inject a custom fetch (useful for tests). Defaults to global fetch. */
+    fetch?: typeof fetch;
+    /** Override the commit author message prefix. */
+    commitMessagePrefix?: string;
+}
+declare class GitHubApiError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly operation: string;
+    readonly path: string;
+    constructor(options: {
+        status: number;
+        statusText: string;
+        operation: string;
+        path: string;
+        body?: string;
+    });
+}
+/**
+ * GitHub Contents API adapter.
+ *
+ * Implements the read-only `StorageAdapter` surface (satisfies `BoardAPI`
+ * consumption in Harbor's remote mode). `writeFile` / `writeFiles` are
+ * concrete methods used only by Harbor's onboarding flows (seed commits,
+ * workspace init, config recovery) — never wired up to the interface
+ * because ongoing task CRUD never routes through GitHub. Delete is
+ * intentionally unimplemented: nothing in the current or planned
+ * architecture ever deletes via the GitHub API.
+ */
+declare class GitHubAdapter implements ReadableStorageAdapter {
+    private owner;
+    private repo;
+    private token;
+    private branch;
+    private fetchImpl;
+    private commitMessagePrefix;
+    constructor(options: GitHubAdapterOptions);
+    private contentsUrl;
+    private contentsReadUrl;
+    private headers;
+    private errorFromResponse;
+    private readFileContent;
+    readFile(path: string): Promise<string>;
+    readFileIfExists(path: string): Promise<string | null>;
+    /** Returns the SHA of an existing file, or undefined if it does not exist. */
+    private getSha;
+    writeFile(path: string, content: string): Promise<void>;
+    listFiles(directory: string): Promise<string[]>;
+    readFiles(paths: string[]): Promise<Map<string, string>>;
+    writeFiles(files: Map<string, string>): Promise<void>;
+}
+
+interface TaskAvailabilityOptions {
+    /** Column whose tasks are candidates. Defaults to `config.default_column`. */
+    status?: string;
+    /** Already-read tasks from `.shipbench/tasks/archive/`. */
+    archivedTasks?: readonly Task[];
+    /** Archive file slugs, including files whose contents did not parse. */
+    archivedSlugs?: Iterable<string>;
+}
+/**
+ * Returns tasks in the actionable column whose dependencies are all complete.
+ * This function is pure and performs no adapter reads.
+ */
+declare function listAvailableTasks(tasks: readonly Task[], config: ShipbenchConfig, options?: TaskAvailabilityOptions): Task[];
+/**
+ * Returns tasks in the actionable column with at least one unsatisfied
+ * dependency. This function is pure and performs no adapter reads.
+ */
+declare function listBlockedTasks(tasks: readonly Task[], config: ShipbenchConfig, options?: TaskAvailabilityOptions): Task[];
+
+declare function loadConfig(adapter: ReadableStorageAdapter, options?: LoadConfigOptions): Promise<ShipbenchConfig>;
+declare function validateConfig(config: ShipbenchConfig): string[];
+
+declare const DEFAULT_CONFIG: ShipbenchConfig;
+
+interface TaskDependencyGraphNode {
+    status: string;
+    depends_on: string[];
+    blocks: string[];
+}
+type TaskDependencyGraph = Record<string, TaskDependencyGraphNode>;
+interface TaskDependencyGraphOptions {
+    /** Already-read tasks from `.shipbench/tasks/archive/`. */
+    archivedTasks?: readonly Task[];
+    /** Archive file slugs, including files whose contents did not parse. */
+    archivedSlugs?: Iterable<string>;
+}
+interface TaskDependencyIndex {
+    liveTasksBySlug: ReadonlyMap<string, Task>;
+    archivedTasksBySlug: ReadonlyMap<string, Task>;
+    /** Archive file identities, including files whose contents did not parse. */
+    archivedSlugs: ReadonlySet<string>;
+}
+type TaskDependencyResolution = {
+    kind: 'live';
+    status: string;
+    task: Task;
+} | {
+    kind: 'archived';
+    status: 'archived';
+    task?: Task;
+} | {
+    kind: 'missing';
+    status: 'missing';
+};
+declare function createTaskDependencyIndex(liveTasks: readonly Task[], archivedTasks?: readonly Task[], archivedSlugs?: Iterable<string>): TaskDependencyIndex;
+declare function resolveTaskDependency(slug: string, index: TaskDependencyIndex): TaskDependencyResolution;
+declare function dependencyStatus(slug: string, index: TaskDependencyIndex): string;
+declare function taskDependenciesAreSatisfied(task: Task, index: TaskDependencyIndex, doneColumn: string): boolean;
+/**
+ * Builds forward and reverse dependency adjacency for live tasks plus any
+ * supplied archived tasks. Referenced slugs outside that set are represented
+ * as missing nodes so callers never need a second lookup.
+ */
+declare function buildTaskDependencyGraph(liveTasks: readonly Task[], options?: TaskDependencyGraphOptions): TaskDependencyGraph;
+
+interface GithubRepositoryParts {
+    owner: string;
+    repo: string;
+}
+declare function parseGithubUrl(input: string): GithubRepositoryParts | null;
+declare function parseGithubRemoteUrl(input: string): GithubRepositoryParts | null;
+declare function normalizeGithubUrl(input: string): string | null;
+declare function normalizeGithubRemoteUrl(input: string): string | null;
+
+interface InitProjectOptions {
+    name: string;
+}
+interface MissingProjectInitializationState {
+    kind: 'missing';
+}
+interface InitializedProjectInitializationState {
+    kind: 'initialized';
+    config: ShipbenchConfig;
+    warnings: ProjectWarning[];
+}
+interface IncompleteProjectInitializationState {
+    kind: 'incomplete';
+    paths: string[];
+}
+interface MalformedProjectInitializationState {
+    kind: 'malformed';
+    errors: string[];
+}
+interface InvalidProjectInitializationState {
+    kind: 'invalid';
+    errors: string[];
+}
+type ProjectInitializationState = MissingProjectInitializationState | InitializedProjectInitializationState | IncompleteProjectInitializationState | MalformedProjectInitializationState | InvalidProjectInitializationState;
+interface InitProjectResult {
+    created: boolean;
+    config: ShipbenchConfig;
+    warnings: ProjectWarning[];
+}
+type FailedProjectInitializationState = Exclude<ProjectInitializationState, MissingProjectInitializationState | InitializedProjectInitializationState>;
+declare class ProjectInitializationError extends Error {
+    readonly state: FailedProjectInitializationState;
+    constructor(state: FailedProjectInitializationState);
+}
+declare function inspectProjectInitialization(adapter: ReadableStorageAdapter): Promise<ProjectInitializationState>;
+declare function initProject(adapter: StorageAdapter, options: InitProjectOptions): Promise<InitProjectResult>;
+
+type TaskSearchField = 'title' | 'tags' | 'body';
+interface TaskSearchMatch {
+    slug: string;
+    title: string;
+    matched_fields: TaskSearchField[];
+    snippet?: string;
+}
+/**
+ * Splits the query on whitespace and finds tasks in which every
+ * case-insensitive term occurs as a substring of a title, tag, or Markdown
+ * body. Terms may occur in different fields. Input order is preserved so
+ * callers can sort before search and limit the returned matches afterward.
+ */
+declare function searchTasks(tasks: readonly Task[], query: string): TaskSearchMatch[];
+
+declare function slugify(title: string): string;
+declare function resolveSlugCollision(slug: string, existingSlugs: Set<string>): string;
+
+type Awaitable<T> = T | PromiseLike<T>;
+interface GetTaskOptions {
+    archived?: boolean;
+}
+interface ListTasksOptions {
+    /** Already-read or concurrently-loading tasks from `tasks/archive/`. */
+    archivedTasks?: Awaitable<readonly Task[]>;
+    /** Archive file slugs, including files whose contents did not parse. */
+    archivedSlugs?: Awaitable<Iterable<string>>;
+}
+declare class ArchiveBlockedError extends Error {
+    readonly slug: string;
+    readonly dependentSlugs: string[];
+    constructor(slug: string, dependentSlugs: string[]);
+}
+declare function listTasks(adapter: ReadableStorageAdapter, config: ShipbenchConfig, options?: ListTasksOptions): Promise<TaskReadResult>;
+declare function getTask(adapter: ReadableStorageAdapter, config: ShipbenchConfig, slug: string, options?: GetTaskOptions): Promise<Task | null>;
+declare function listArchivedTasks(adapter: ReadableStorageAdapter, config: ShipbenchConfig): Promise<TaskReadResult>;
+/**
+ * Returns every task-file slug represented by a read, including malformed files
+ * that produced a warning instead of a Task.
+ */
+declare function taskFileSlugs(result: TaskReadResult): string[];
+declare function createTask(adapter: StorageAdapter, config: ShipbenchConfig, title: string, fields?: Partial<TaskFrontmatter>): Promise<Task>;
+declare function updateTask(adapter: StorageAdapter, config: ShipbenchConfig, slug: string, fields: Partial<TaskFrontmatter>, body?: string): Promise<{
+    task: Task;
+    layout?: BoardLayout;
+}>;
+declare function addComment(adapter: StorageAdapter, config: ShipbenchConfig, slug: string, text: string): Promise<Task>;
+declare function editComment(adapter: StorageAdapter, config: ShipbenchConfig, slug: string, index: number, text: string): Promise<Task>;
+declare function deleteComment(adapter: StorageAdapter, config: ShipbenchConfig, slug: string, index: number): Promise<Task>;
+/**
+ * Move a task to a (possibly different) column and position. `position` is a
+ * 0-based index into the destination column's `layout` entry; `-1` appends.
+ * Writes the task file only when status changes; always writes layout.json
+ * with the updated order. Returns both the (possibly status-changed) task
+ * and the authoritative new layout so callers can reconcile.
+ */
+declare function reorderTask(adapter: StorageAdapter, config: ShipbenchConfig, slug: string, toStatus: string, position: number): Promise<{
+    task: Task;
+    layout: BoardLayout;
+}>;
+declare function moveTask(adapter: StorageAdapter, config: ShipbenchConfig, slug: string, toStatus: string): Promise<Task>;
+declare function deleteTask(adapter: StorageAdapter, config: ShipbenchConfig, slug: string): Promise<void>;
+declare function archiveTask(adapter: StorageAdapter, config: ShipbenchConfig, slug: string, options?: {
+    force?: boolean;
+}): Promise<Task>;
+declare function unarchiveTask(adapter: StorageAdapter, config: ShipbenchConfig, slug: string): Promise<Task>;
+
+export { ArchiveBlockedError, BoardLayout, DEFAULT_CONFIG, FsAdapter, type GetTaskOptions, GitHubAdapter, GitHubApiError, type GithubRepositoryParts, type InitProjectOptions, type InitProjectResult, type ListTasksOptions, LoadConfigOptions, ProjectInitializationError, type ProjectInitializationState, ProjectWarning, ReadableStorageAdapter, ShipbenchConfig, StorageAdapter, Task, type TaskAvailabilityOptions, type TaskDependencyGraph, type TaskDependencyGraphNode, type TaskDependencyGraphOptions, type TaskDependencyIndex, type TaskDependencyResolution, TaskFrontmatter, TaskReadResult, type TaskSearchField, type TaskSearchMatch, addComment, archiveTask, buildTaskDependencyGraph, createTask, createTaskDependencyIndex, deleteComment, deleteTask, dependencyStatus, editComment, getTask, initProject, inspectProjectInitialization, listArchivedTasks, listAvailableTasks, listBlockedTasks, listTasks, loadConfig, moveTask, normalizeGithubRemoteUrl, normalizeGithubUrl, parseGithubRemoteUrl, parseGithubUrl, reorderTask, resolveSlugCollision, resolveTaskDependency, searchTasks, slugify, taskDependenciesAreSatisfied, taskFileSlugs, unarchiveTask, updateTask, validateConfig };