@deskwork/core 0.9.5

package/dist/scaffold.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Blog post scaffolder.
+ *
+ * Creates the markdown file for a calendar entry with YAML frontmatter
+ * matching the host project's conventions. Called by the outline skill
+ * for entries with `contentType: 'blog'`. YouTube and tool entries
+ * skip this step entirely.
+ *
+ * Knobs (all per-site config):
+ *   - blogFilenameTemplate  path template under contentDir. `{slug}` is
+ *                           replaced. Default `"{slug}/index.md"`.
+ *   - blogLayout            if set, emit `layout: <value>` frontmatter
+ *   - blogInitialState      if set, emit `state: <value>` frontmatter
+ *                           (typical: `"draft"` to gate prod builds)
+ *   - blogOutlineSection    if true, body includes `## Outline` section
+ *
+ * Author comes from `config.author` (or an explicit override).
+ */
+import type { CalendarEntry } from './types.ts';
+import type { DeskworkConfig } from './config.ts';
+import type { ContentIndex } from './content-index.ts';
+export interface ScaffoldResult {
+    /** Absolute path to the created markdown file */
+    filePath: string;
+    /** Path relative to the project root */
+    relativePath: string;
+    /**
+     * Path of the file relative to `contentDir` — reported to the
+     * caller so it can show the operator where the file landed. The
+     * file's connection to the calendar entry is now carried by its
+     * frontmatter `id:` field, not by a path string on the calendar
+     * row (Phase 19a).
+     */
+    contentRelativePath: string;
+}
+/** Layout options for `scaffoldBlogPost`. Picks the on-disk shape. */
+export type ScaffoldLayout = 'index' | 'readme' | 'flat';
+export interface ScaffoldOptions {
+    /** Override `config.author` for this post. */
+    authorOverride?: string;
+    /**
+     * Pick the on-disk shape of the scaffolded file. When omitted, falls
+     * back to the site's `blogFilenameTemplate` (preserving legacy
+     * audiocontrol behavior).
+     *
+     * - `'index'` → `<slug>/index.md` (hub-style, public route in most
+     *   single-level Astro patterns)
+     * - `'readme'` → `<slug>/README.md` (editorial-private — directory
+     *   exists, but content collections that match `*\/index.md` won't
+     *   pick it up)
+     * - `'flat'` → `<slug>.md` (a sibling file at the parent dir, no
+     *   own directory; useful for many small chapters under one parent)
+     */
+    layout?: ScaffoldLayout;
+    /**
+     * Pre-built content index (per-request memoization). When omitted,
+     * the scaffolder builds one fresh. Used for the duplicate-binding
+     * preflight (Issue #66): if the entry's id already binds a file
+     * elsewhere under contentDir, refuse to scaffold a parallel file.
+     */
+    index?: ContentIndex;
+}
+/**
+ * Create the blog post markdown for a calendar entry.
+ */
+export declare function scaffoldBlogPost(projectRoot: string, config: DeskworkConfig, site: string | null | undefined, entry: CalendarEntry, opts?: ScaffoldOptions): ScaffoldResult;
+//# sourceMappingURL=scaffold.d.ts.map

package/dist/scaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAKvD,MAAM,WAAW,cAAc;IAC7B,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,sEAAsE;AACtE,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEzD,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC/B,KAAK,EAAE,aAAa,EACpB,IAAI,GAAE,eAAoB,GACzB,cAAc,CA2FhB"}

package/dist/scaffold.js

@@ -0,0 +1,122 @@
+/**
+ * Blog post scaffolder.
+ *
+ * Creates the markdown file for a calendar entry with YAML frontmatter
+ * matching the host project's conventions. Called by the outline skill
+ * for entries with `contentType: 'blog'`. YouTube and tool entries
+ * skip this step entirely.
+ *
+ * Knobs (all per-site config):
+ *   - blogFilenameTemplate  path template under contentDir. `{slug}` is
+ *                           replaced. Default `"{slug}/index.md"`.
+ *   - blogLayout            if set, emit `layout: <value>` frontmatter
+ *   - blogInitialState      if set, emit `state: <value>` frontmatter
+ *                           (typical: `"draft"` to gate prod builds)
+ *   - blogOutlineSection    if true, body includes `## Outline` section
+ *
+ * Author comes from `config.author` (or an explicit override).
+ */
+import { existsSync, mkdirSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { buildContentIndex } from "./content-index.js";
+import { resolveSite, resolveBlogFilePath } from "./paths.js";
+import { writeFrontmatter } from "./frontmatter.js";
+/**
+ * Create the blog post markdown for a calendar entry.
+ */
+export function scaffoldBlogPost(projectRoot, config, site, entry, opts = {}) {
+    const slug = resolveSite(config, site);
+    const siteCfg = config.sites[slug];
+    const author = opts.authorOverride ?? config.author;
+    if (!author) {
+        throw new Error(`Cannot scaffold blog post: no author configured. ` +
+            `Set "author" at the top level of .deskwork/config.json, or pass an explicit author.`);
+    }
+    // The `deskwork.id` field binds this file to its CalendarEntry
+    // refactor-proof. Phase 19 made entry id (UUID) the canonical internal
+    // identifier; writing it into frontmatter lets the content-index pick
+    // this file up regardless of slug renames or fs relocations. The id
+    // lives under a `deskwork:` namespace (Issue #38) so deskwork doesn't
+    // claim the global top-level `id:` keyspace — operators may use that
+    // freely. `addEntry` always sets `entry.id` to a UUID; if it's missing
+    // here we have a real bug upstream — fail loud rather than scaffold an
+    // unbindable file. Validated UP FRONT so the duplicate-binding check
+    // below can rely on it.
+    if (!entry.id || entry.id.trim() === '') {
+        throw new Error('Cannot scaffold entry without id; this is a bug in calendar-mutations or upstream. ' +
+            `Entry slug: "${entry.slug}".`);
+    }
+    // Issue #66: if this entry's id is already bound to a file elsewhere
+    // under contentDir, refuse to scaffold a parallel file. Two files
+    // sharing the same `deskwork.id` is exactly the duplicate-id state
+    // doctor flags; better to bail here with an actionable message than
+    // create the bug.
+    const index = opts.index ?? buildContentIndex(projectRoot, config, slug);
+    const existingBinding = index.byId.get(entry.id);
+    if (existingBinding !== undefined) {
+        const existingRel = relative(projectRoot, existingBinding);
+        throw new Error(`Cannot scaffold: entry "${entry.slug}" is already bound to file at ` +
+            `"${existingRel}". Use that file directly, or unbind it first ` +
+            `(remove its frontmatter \`deskwork.id\`) before scaffolding a new one.`);
+    }
+    // When a layout is requested, compute the contentDir-relative path
+    // explicitly. Otherwise fall back to the site template.
+    const contentRelativePath = opts.layout
+        ? layoutToContentRelativePath(opts.layout, entry.slug)
+        : undefined;
+    const filePath = resolveBlogFilePath(projectRoot, config, slug, entry.slug, contentRelativePath);
+    const relativePath = relative(projectRoot, filePath);
+    if (existsSync(filePath)) {
+        throw new Error(`Blog post already exists at ${relativePath}`);
+    }
+    const dateStr = new Date().toISOString().slice(0, 10);
+    const data = {};
+    // `deskwork` block first so it's the visually-stable top of the
+    // frontmatter — operators reading the file see the namespaced
+    // binding immediately and won't mistake it for a host-rendering field.
+    data.deskwork = { id: entry.id };
+    if (siteCfg.blogLayout)
+        data.layout = siteCfg.blogLayout;
+    data.title = entry.title;
+    data.description = entry.description;
+    data.date = formatDateHuman(dateStr);
+    data.datePublished = dateStr;
+    data.dateModified = dateStr;
+    data.author = author;
+    if (siteCfg.blogInitialState)
+        data.state = siteCfg.blogInitialState;
+    const body = buildBody(entry.title, siteCfg.blogOutlineSection === true);
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFrontmatter(filePath, data, body);
+    // Always report the contentDir-relative path so the caller can show
+    // the operator where the file landed. When no explicit layout was
+    // requested we derive it from the resolved file path.
+    const reported = contentRelativePath ??
+        relative(join(projectRoot, siteCfg.contentDir), filePath);
+    return { filePath, relativePath, contentRelativePath: reported };
+}
+/** Map a ScaffoldLayout + slug to the contentDir-relative file path. */
+function layoutToContentRelativePath(layout, slug) {
+    switch (layout) {
+        case 'index':
+            return `${slug}/index.md`;
+        case 'readme':
+            return `${slug}/README.md`;
+        case 'flat':
+            return `${slug}.md`;
+    }
+}
+function buildBody(title, withOutline) {
+    const parts = ['', `# ${title}`, ''];
+    if (withOutline) {
+        parts.push('## Outline', '', '<!-- Sketch the shape of the post here before drafting the body. -->', '');
+    }
+    parts.push('<!-- Write your post here -->', '');
+    return parts.join('\n');
+}
+/** Format a date as "Month YYYY" (e.g. "March 2026"). */
+function formatDateHuman(isoDate) {
+    const d = new Date(`${isoDate}T00:00:00`);
+    return d.toLocaleDateString('en-US', { month: 'long', year: 'numeric' });
+}
+//# sourceMappingURL=scaffold.js.map

package/dist/scaffold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"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"}

package/dist/scrapbook.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Scrapbook helpers — the per-article `<contentDir>/<slug>/scrapbook/`
+ * directory. The scrapbook is a working-notes home for receipts,
+ * research, and references attached to an in-flight article. Committed
+ * to git alongside the article; not baked to the public site.
+ *
+ * Responsibilities:
+ *   - Resolve + validate slug + filename (reject `..`, absolute paths,
+ *     and anything outside the article's scrapbook dir)
+ *   - List + read + mutate files inside one scrapbook
+ *   - Classify files by extension into the design type buckets
+ *   - Format relative mtime + total size for the studio chip / viewer
+ *
+ * The API endpoints that wrap these helpers should 404 in PROD; this
+ * library contains no PROD check of its own (enforcement stays at the
+ * endpoint boundary).
+ */
+import type { DeskworkConfig } from './config.ts';
+import type { ContentIndex } from './content-index.ts';
+/** Type buckets for scrapbook entries. */
+export type ScrapbookItemKind = 'md' | 'json' | 'js' | 'img' | 'txt' | 'other';
+export interface ScrapbookItem {
+    name: string;
+    kind: ScrapbookItemKind;
+    size: number;
+    mtime: string;
+}
+export interface ScrapbookSummary {
+    site: string;
+    /**
+     * The scrapbook's location identifier — a slug for entries tied to a
+     * calendar row, or any directory path within `contentDir` for
+     * scrapbooks that hang off purely organizational nodes (e.g. an
+     * intermediate project directory that isn't itself a calendar entry).
+     */
+    slug: string;
+    dir: string;
+    exists: boolean;
+    /** Files at the top of `scrapbook/` (public/published-side notes). */
+    items: ScrapbookItem[];
+    /**
+     * Files inside `scrapbook/secret/` — never to be published. Operators
+     * can drop research, drafts, or sensitive notes here knowing the host
+     * project's content collection patterns won't pick them up.
+     */
+    secretItems: ScrapbookItem[];
+}
+/** Well-known subdirectory name for editorially-private scrapbook items. */
+export declare const SECRET_SUBDIR = "secret";
+/**
+ * A single slug segment — kebab-case lowercase. Used both for flat
+ * slugs and as the building block of hierarchical paths.
+ */
+declare const SLUG_SEGMENT_RE: RegExp;
+export declare function assertSlug(slug: string): void;
+/**
+ * Split a hierarchical slug into its segments. Each segment is a
+ * standalone kebab-case identifier.
+ */
+export declare function slugSegments(slug: string): string[];
+/**
+ * True if a slug refers to a nested entry (has at least one `/`).
+ */
+export declare function isNestedSlug(slug: string): boolean;
+export { SLUG_SEGMENT_RE };
+export declare function assertFilename(name: string): void;
+/**
+ * Resolve the scrapbook directory for (site, slug) and ensure the
+ * return path stays inside the site's content directory.
+ * Doesn't require the directory to exist.
+ */
+export declare function scrapbookDir(projectRoot: string, config: DeskworkConfig, site: string, slug: string): string;
+/**
+ * Resolve the scrapbook directory for an arbitrary path under the site's
+ * content directory. Used by Phase 19c+ callers (e.g. the studio) that
+ * already know the fs-relative path of an organizational or tracked node
+ * and don't want to re-derive it through the slug regex. The path may
+ * contain `/` segments; no `..` or absolute paths allowed.
+ *
+ * Path-shape validation matches `assertSlug` since the on-disk layout
+ * is the same shape — kebab-case segments separated by `/`. Different
+ * helper, same constraint.
+ */
+export declare function scrapbookDirAtPath(projectRoot: string, config: DeskworkConfig, site: string, relPath: string): string;
+/**
+ * Resolve the scrapbook directory for a tracked calendar entry.
+ *
+ * Derives the scrapbook location from the parent directory of the
+ * entry's content file (located via `findEntryFile`, which prefers the
+ * frontmatter-id index over the slug template). Falls back to today's
+ * slug-based addressing for entries that haven't been bound to
+ * frontmatter yet (pre-doctor state).
+ *
+ * Refactor-proof: when the operator renames an entry's directory on
+ * disk, the next request rebuilds the index and the scrapbook now
+ * lives at the new path automatically.
+ *
+ * @param entry Calendar entry — `id` preferred (Phase 19+); `slug` is
+ *              used both as the legacy fallback and to locate the
+ *              `<dirname>/scrapbook/` when the entry has no id yet.
+ * @param index Optional pre-built index (per-request memoization). When
+ *              omitted, this function builds one.
+ */
+export declare function scrapbookDirForEntry(projectRoot: string, config: DeskworkConfig, site: string, entry: {
+    id?: string;
+    slug: string;
+}, index?: ContentIndex): string;
+/** Options that select between the public scrapbook root and `secret/`. */
+export interface ScrapbookLocation {
+    /** When true, the file lives under `scrapbook/secret/`. Default: false. */
+    secret?: boolean;
+}
+/**
+ * Resolve a filename INSIDE a scrapbook dir and return the absolute
+ * path. Throws if the resolved path escapes the scrapbook dir (guards
+ * against `..` sequences that slipped through assertFilename).
+ *
+ * When `opts.secret` is true, the returned path is rooted at
+ * `<scrapbook>/secret/<filename>` instead of `<scrapbook>/<filename>`.
+ */
+export declare function scrapbookFilePath(projectRoot: string, config: DeskworkConfig, site: string, slug: string, filename: string, opts?: ScrapbookLocation): string;
+export declare function classify(filename: string): ScrapbookItemKind;
+/**
+ * List the items in a scrapbook, sorted newest-mtime first. Returns
+ * both public items (top-level files) and secret items (files inside
+ * `scrapbook/secret/`). Subdirectories at the top level OTHER than
+ * `secret/` are ignored — deskwork doesn't recurse into arbitrary
+ * trees inside a scrapbook.
+ */
+export declare function listScrapbook(projectRoot: string, config: DeskworkConfig, site: string, slug: string): ScrapbookSummary;
+/**
+ * List a scrapbook by absolute directory path. Used by callers that
+ * have already resolved the on-disk path via `scrapbookDirForEntry`
+ * (id-driven) or `scrapbookDirAtPath` (fs-path-driven) and don't want
+ * to re-derive through the slug template. The `slug` parameter is only
+ * used to populate the returned summary's identifier field — it does
+ * not influence path resolution.
+ *
+ * Internal primitive shared by `listScrapbook` (slug-based) and
+ * `listScrapbookForEntry` (id-driven).
+ */
+export declare function listScrapbookAtDir(site: string, slug: string, dir: string): ScrapbookSummary;
+/**
+ * List scrapbook items for a tracked calendar entry. Resolves the
+ * scrapbook directory via the content index when available (id binding),
+ * falling back to slug-based addressing for entries that haven't been
+ * bound to frontmatter yet (pre-doctor state).
+ *
+ * Mirrors the shape of `countScrapbookForEntry`. Used by the studio
+ * review-page drawer + content-detail panel so writingcontrol-shape
+ * entries (where the file path diverges from the slug template) list
+ * items at the correct on-disk location.
+ *
+ * @param entry Calendar entry — `id` preferred; `slug` is both the
+ *              legacy fallback and the disambiguator the underlying
+ *              resolver uses when the index is incomplete.
+ * @param index Optional pre-built per-request index. When omitted, the
+ *              resolver builds one on demand.
+ */
+export declare function listScrapbookForEntry(projectRoot: string, config: DeskworkConfig, site: string, entry: {
+    id?: string;
+    slug: string;
+}, index?: ContentIndex): ScrapbookSummary;
+/**
+ * Total item count (public + secret). Used by the studio chip for the
+ * badge — operators want a single "has scrapbook content" signal that
+ * counts everything attached to this entry.
+ *
+ * Slug-based addressing: resolves `<contentDir>/<slug>/scrapbook/`. For
+ * entries whose on-disk path doesn't match the slug template (e.g.
+ * writingcontrol-shape projects where slug `the-outbound` lives at
+ * `projects/the-outbound/index.md`), use `countScrapbookForEntry`
+ * instead — it derives the path from the bound file via the content
+ * index.
+ */
+export declare function countScrapbook(projectRoot: string, config: DeskworkConfig, site: string, slug: string): number;
+/**
+ * Count scrapbook items for a tracked calendar entry. Resolves the
+ * scrapbook directory via the content index when available (id binding),
+ * falling back to slug-based addressing for entries that haven't been
+ * bound to frontmatter yet (pre-doctor state).
+ *
+ * Mirrors the shape of `scrapbookDirForEntry` — same resolver, same
+ * legacy-slug fallback. Used by the studio dashboard chip so writing-
+ * control-shape entries (where the file path diverges from the slug
+ * template) report the correct count.
+ *
+ * @param entry Calendar entry — `id` preferred (Phase 19+); `slug` is
+ *              both the legacy fallback and the disambiguator the
+ *              underlying resolver uses when the index is incomplete.
+ * @param index Optional pre-built per-request index. When omitted, the
+ *              resolver builds one on demand.
+ */
+export declare function countScrapbookForEntry(projectRoot: string, config: DeskworkConfig, site: string, entry: {
+    id?: string;
+    slug: string;
+}, index?: ContentIndex): number;
+export declare function readScrapbookFile(projectRoot: string, config: DeskworkConfig, site: string, slug: string, filename: string, opts?: ScrapbookLocation): {
+    name: string;
+    kind: ScrapbookItemKind;
+    size: number;
+    mtime: string;
+    content: Buffer;
+};
+/**
+ * Create a new markdown note in the scrapbook. Creates the scrapbook
+ * dir (and `secret/` subdir, if needed) if it doesn't exist. Refuses
+ * to overwrite existing files.
+ */
+export declare function createScrapbookMarkdown(projectRoot: string, config: DeskworkConfig, site: string, slug: string, filename: string, body: string, opts?: ScrapbookLocation): ScrapbookItem;
+/** Overwrite an existing file's contents. Refuses if the file is absent. */
+export declare function saveScrapbookFile(projectRoot: string, config: DeskworkConfig, site: string, slug: string, filename: string, body: string | Buffer, opts?: ScrapbookLocation): ScrapbookItem;
+export declare function renameScrapbookFile(projectRoot: string, config: DeskworkConfig, site: string, slug: string, oldName: string, newName: string, opts?: ScrapbookLocation): ScrapbookItem;
+export declare function deleteScrapbookFile(projectRoot: string, config: DeskworkConfig, site: string, slug: string, filename: string, opts?: ScrapbookLocation): void;
+/**
+ * Seed a scrapbook's `README.md` at plan time. Idempotent — if the
+ * README already exists, returns null without touching it. Used by
+ * the plan skill so every Planned article gets a scrapbook home with
+ * a template that names the article and invites receipts.
+ */
+export declare function seedScrapbookReadme(projectRoot: string, config: DeskworkConfig, site: string, slug: string, title: string): ScrapbookItem | null;
+/**
+ * Write an uploaded file into the scrapbook. Filename + content come
+ * from the multipart body upstream; we validate and persist.
+ */
+export declare function writeScrapbookUpload(projectRoot: string, config: DeskworkConfig, site: string, slug: string, filename: string, content: Buffer, opts?: ScrapbookLocation): ScrapbookItem;
+export declare function formatRelativeTime(iso: string, now?: Date): string;
+export declare function formatSize(bytes: number): string;
+//# sourceMappingURL=scrapbook.d.ts.map

package/dist/scrapbook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scrapbook.d.ts","sourceRoot":"","sources":["../src/scrapbook.ts"],"names":[],"mappings":"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"}