@deskwork/core 0.9.5

package/dist/outline-split.js

@@ -0,0 +1,84 @@
+/*
+ * outline-split.ts — shared utility for separating the `## Outline`
+ * section from the rest of a dispatch markdown document.
+ *
+ * The outline lives in the source file (SSOT: the markdown file IS
+ * the article, including its outline). But during body editing the
+ * operator doesn't want the outline cluttering the source view —
+ * it's reference material, not editing material, once the
+ * Outlining phase is approved. The editor splits on mount, presents
+ * only the body for editing, and rejoins on save so the disk file
+ * is never lossy.
+ *
+ * Shape:
+ *   splitOutline(md)          → { outline, body, present }
+ *   joinOutline(outline, body) → md
+ *
+ * The split round-trips losslessly: `joinOutline(...splitOutline(x))`
+ * equals the original document whenever `splitOutline(x).present`
+ * is true. When no outline is present, `outline` is empty and join
+ * returns just the body.
+ */
+/**
+ * Detect and separate the `## Outline` section. The section runs
+ * from its `## Outline` heading through the next `## ` heading
+ * (non-inclusive) or end of file. Anything before the outline is
+ * prepended to `body`; anything after is appended. Rejoin via
+ * `joinOutline`.
+ *
+ * This mirrors the line-wise logic in `scripts/lib/editorial/
+ * body-state.ts` (kept separate so the browser-side bundle
+ * doesn't have to drag in the server's fs/path imports).
+ */
+export function splitOutline(md) {
+    const lines = md.split('\n');
+    const startIdx = lines.findIndex((line) => /^##[ \t]+Outline\b/.test(line));
+    if (startIdx < 0) {
+        return { outline: '', body: md, present: false, startLine: -1, endLine: -1 };
+    }
+    let endIdx = lines.length;
+    for (let i = startIdx + 1; i < lines.length; i++) {
+        if (/^##[ \t]+/.test(lines[i])) {
+            endIdx = i;
+            break;
+        }
+    }
+    const outline = lines.slice(startIdx, endIdx).join('\n');
+    const body = [...lines.slice(0, startIdx), ...lines.slice(endIdx)].join('\n');
+    return { outline, body, present: true, startLine: startIdx, endLine: endIdx };
+}
+/**
+ * Rejoin an outline section with body content. If `outline` is
+ * empty, returns `body` unchanged. Otherwise splices the outline
+ * back at the same structural position it was extracted from —
+ * which for the scaffold shape (frontmatter + H1 + outline + body
+ * sections) is right after the H1.
+ *
+ * Strategy: find the first `## ` heading in `body` and insert the
+ * outline immediately before it, separated by a blank line on each
+ * side. If the body has no H2 (e.g., pre-drafting, still just
+ * frontmatter + H1), append outline at the end.
+ */
+export function joinOutline(outline, body) {
+    if (!outline)
+        return body;
+    const outlineTrimmed = outline.replace(/\n+$/, '');
+    const bodyLines = body.split('\n');
+    const firstH2 = bodyLines.findIndex((line) => /^##[ \t]+/.test(line));
+    if (firstH2 < 0) {
+        // No H2 in body — append outline to the end. Preserves the
+        // scaffold shape where only frontmatter + H1 exist yet.
+        const trailingNewline = body.endsWith('\n') ? '' : '\n';
+        return `${body}${trailingNewline}\n${outlineTrimmed}\n`;
+    }
+    const before = bodyLines.slice(0, firstH2);
+    const after = bodyLines.slice(firstH2);
+    // Ensure exactly one blank line separates outline from the
+    // following H2, and that the outline ends without trailing
+    // newlines (we control the separator).
+    while (before.length > 0 && before[before.length - 1] === '') {
+        before.pop();
+    }
+    return [...before, '', outlineTrimmed, '', ...after].join('\n');
+}
+//# sourceMappingURL=outline-split.js.map

package/dist/outline-split.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outline-split.js","sourceRoot":"","sources":["../src/outline-split.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAeH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAAC,EAAU;IACrC,MAAM,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC7B,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5E,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QACjB,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC;IAC/E,CAAC;IACD,IAAI,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC1B,KAAK,IAAI,CAAC,GAAG,QAAQ,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACjD,IAAI,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/B,MAAM,GAAG,CAAC,CAAC;YACX,MAAM;QACR,CAAC;IACH,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzD,MAAM,IAAI,GAAG,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9E,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AAChF,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe,EAAE,IAAY;IACvD,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,MAAM,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACnD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACtE,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAChB,2DAA2D;QAC3D,wDAAwD;QACxD,MAAM,eAAe,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QACxD,OAAO,GAAG,IAAI,GAAG,eAAe,KAAK,cAAc,IAAI,CAAC;IAC1D,CAAC;IACD,MAAM,MAAM,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAC3C,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACvC,2DAA2D;IAC3D,2DAA2D;IAC3D,uCAAuC;IACvC,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC;QAC7D,MAAM,CAAC,GAAG,EAAE,CAAC;IACf,CAAC;IACD,OAAO,CAAC,GAAG,MAAM,EAAE,EAAE,EAAE,cAAc,EAAE,EAAE,EAAE,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAClE,CAAC"}

package/dist/overrides.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Override resolver — phase 23f.
+ *
+ * The customization layer lets operators drop a file into
+ * `<projectRoot>/.deskwork/<category>/<name>` and have the plugin pick
+ * it up at runtime instead of the built-in default. Three categories
+ * exist today: `templates` (studio page renderers), `prompts`
+ * (reserved — no defaults yet), and `doctor` (runner rules).
+ *
+ * This module is the lookup contract. Each method takes a base name
+ * (no extension) and returns the absolute path of an override file if
+ * one exists, or `null` otherwise. Callers decide what to do with the
+ * returned path:
+ *   - studio page renderers `await import(path)` and call the module's
+ *     `default` export with the same arguments the built-in renderer
+ *     expected;
+ *   - the doctor runner discovers project rules via the directory
+ *     listing path (see `doctor/runner.ts`); the resolver method here
+ *     is for one-off basename-collision lookups.
+ *
+ * Discovery is sync and uses `existsSync` — there is no caching. The
+ * project root is captured at construction time, so the resolver is
+ * cheap to create per-request if needed.
+ *
+ * Filename convention: callers pass names without extension. The
+ * resolver checks for `.ts` files first (the documented contract); if
+ * that doesn't exist it returns `null`. We only support TypeScript
+ * source — operators are expected to author overrides as TS modules
+ * the plugin's runtime tsx loader can execute.
+ *
+ * Override module contract for `templates`:
+ *   ```ts
+ *   import type { StudioContext } from '@deskwork/studio/routes/api';
+ *   export default function (ctx: StudioContext, ...args): string;
+ *   ```
+ *   The exact `args` shape mirrors whatever the built-in renderer
+ *   expects (see each `pages/<name>.ts`). The override's return type
+ *   must match too (`string` HTML for sync renderers, `Promise<string>`
+ *   for async ones).
+ *
+ * Override module contract for `doctor`:
+ *   ```ts
+ *   import type { DoctorRule } from '@deskwork/core/doctor';
+ *   const rule: DoctorRule = { ... };
+ *   export default rule;
+ *   ```
+ *   The rule's `id` is what the runner uses for fix-by-id lookups; if
+ *   the basename matches a built-in rule basename, the project rule
+ *   wins (see `doctor/runner.ts` for the merge logic).
+ *
+ * `prompts` is reserved — no default sources exist yet, so the
+ * resolver just returns paths if they happen to be present. Future
+ * deskwork features will pin a default-source mapping for this
+ * category.
+ */
+export type OverrideCategory = 'templates' | 'prompts' | 'doctor';
+export interface OverrideResolver {
+    /** Look up a `templates/<name>.ts` override. */
+    template(name: string): string | null;
+    /** Look up a `prompts/<name>.ts` override. */
+    prompt(name: string): string | null;
+    /** Look up a `doctor/<name>.ts` override. */
+    doctorRule(name: string): string | null;
+    /**
+     * Absolute path of the `.deskwork/<category>` directory the resolver
+     * watches. Useful for callers that want to enumerate every override
+     * (the doctor runner does this to merge project rules with built-in
+     * rules). Returns the directory path even when it doesn't exist —
+     * the caller checks `existsSync` if it cares.
+     */
+    categoryDir(category: OverrideCategory): string;
+}
+/**
+ * Build a resolver scoped to `projectRoot`. The factory captures the
+ * project root once; subsequent lookups join `<projectRoot>/.deskwork/`
+ * with the category and basename.
+ *
+ * Sync by design — every studio request needs to consult the resolver
+ * before deciding which renderer to dispatch, and an `await` on the
+ * fast-path would cost a microtask hop on every request.
+ */
+export declare function createOverrideResolver(projectRoot: string): OverrideResolver;
+//# sourceMappingURL=overrides.d.ts.map

package/dist/overrides.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overrides.d.ts","sourceRoot":"","sources":["../src/overrides.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAKH,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;AAElE,MAAM,WAAW,gBAAgB;IAC/B,gDAAgD;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACtC,8CAA8C;IAC9C,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACpC,6CAA6C;IAC7C,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACxC;;;;;;OAMG;IACH,WAAW,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAAC;CACjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB,CAsB5E"}

package/dist/overrides.js

@@ -0,0 +1,88 @@
+/**
+ * Override resolver — phase 23f.
+ *
+ * The customization layer lets operators drop a file into
+ * `<projectRoot>/.deskwork/<category>/<name>` and have the plugin pick
+ * it up at runtime instead of the built-in default. Three categories
+ * exist today: `templates` (studio page renderers), `prompts`
+ * (reserved — no defaults yet), and `doctor` (runner rules).
+ *
+ * This module is the lookup contract. Each method takes a base name
+ * (no extension) and returns the absolute path of an override file if
+ * one exists, or `null` otherwise. Callers decide what to do with the
+ * returned path:
+ *   - studio page renderers `await import(path)` and call the module's
+ *     `default` export with the same arguments the built-in renderer
+ *     expected;
+ *   - the doctor runner discovers project rules via the directory
+ *     listing path (see `doctor/runner.ts`); the resolver method here
+ *     is for one-off basename-collision lookups.
+ *
+ * Discovery is sync and uses `existsSync` — there is no caching. The
+ * project root is captured at construction time, so the resolver is
+ * cheap to create per-request if needed.
+ *
+ * Filename convention: callers pass names without extension. The
+ * resolver checks for `.ts` files first (the documented contract); if
+ * that doesn't exist it returns `null`. We only support TypeScript
+ * source — operators are expected to author overrides as TS modules
+ * the plugin's runtime tsx loader can execute.
+ *
+ * Override module contract for `templates`:
+ *   ```ts
+ *   import type { StudioContext } from '@deskwork/studio/routes/api';
+ *   export default function (ctx: StudioContext, ...args): string;
+ *   ```
+ *   The exact `args` shape mirrors whatever the built-in renderer
+ *   expects (see each `pages/<name>.ts`). The override's return type
+ *   must match too (`string` HTML for sync renderers, `Promise<string>`
+ *   for async ones).
+ *
+ * Override module contract for `doctor`:
+ *   ```ts
+ *   import type { DoctorRule } from '@deskwork/core/doctor';
+ *   const rule: DoctorRule = { ... };
+ *   export default rule;
+ *   ```
+ *   The rule's `id` is what the runner uses for fix-by-id lookups; if
+ *   the basename matches a built-in rule basename, the project rule
+ *   wins (see `doctor/runner.ts` for the merge logic).
+ *
+ * `prompts` is reserved — no default sources exist yet, so the
+ * resolver just returns paths if they happen to be present. Future
+ * deskwork features will pin a default-source mapping for this
+ * category.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Build a resolver scoped to `projectRoot`. The factory captures the
+ * project root once; subsequent lookups join `<projectRoot>/.deskwork/`
+ * with the category and basename.
+ *
+ * Sync by design — every studio request needs to consult the resolver
+ * before deciding which renderer to dispatch, and an `await` on the
+ * fast-path would cost a microtask hop on every request.
+ */
+export function createOverrideResolver(projectRoot) {
+    const root = join(projectRoot, '.deskwork');
+    function lookup(category, name) {
+        const path = join(root, category, `${name}.ts`);
+        return existsSync(path) ? path : null;
+    }
+    return {
+        template(name) {
+            return lookup('templates', name);
+        },
+        prompt(name) {
+            return lookup('prompts', name);
+        },
+        doctorRule(name) {
+            return lookup('doctor', name);
+        },
+        categoryDir(category) {
+            return join(root, category);
+        },
+    };
+}
+//# sourceMappingURL=overrides.js.map

package/dist/overrides.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overrides.js","sourceRoot":"","sources":["../src/overrides.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAqBjC;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CAAC,WAAmB;IACxD,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IAE5C,SAAS,MAAM,CAAC,QAA0B,EAAE,IAAY;QACtD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,IAAI,KAAK,CAAC,CAAC;QAChD,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IACxC,CAAC;IAED,OAAO;QACL,QAAQ,CAAC,IAAY;YACnB,OAAO,MAAM,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;QACnC,CAAC;QACD,MAAM,CAAC,IAAY;YACjB,OAAO,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QACjC,CAAC;QACD,UAAU,CAAC,IAAY;YACrB,OAAO,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAChC,CAAC;QACD,WAAW,CAAC,QAA0B;YACpC,OAAO,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC9B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/paths.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Path and site resolution against a DeskworkConfig.
+ *
+ * Every skill that touches disk goes through these helpers so that hardcoded
+ * paths — and assumptions about which sites exist — stay out of skill logic.
+ *
+ * Phase 19c — entry-to-file resolution precedence
+ * -----------------------------------------------
+ * For locating the markdown file backing a calendar entry, the canonical
+ * order is:
+ *
+ *   1. **Content index** — when an entry id is known, scan
+ *      `<contentDir>/` for a markdown file whose frontmatter `id:`
+ *      matches. This is refactor-proof: the binding moves with the file
+ *      because the id lives inside the file.
+ *   2. **Slug-template fallback** — when the index has no record (entry
+ *      not bound to frontmatter yet, e.g. pre-doctor state), fall back
+ *      to the site's `blogFilenameTemplate` keyed by slug. This
+ *      preserves audiocontrol-shaped flat-blog behavior unchanged.
+ *
+ * `findEntryFile` implements this precedence directly. `resolveBlogFilePath`
+ * remains the legacy slug-template-only entry point used by callers that
+ * don't have an entry id available (scaffold for new files, doctor's
+ * candidate-search by template, the legacy publish path). New code with
+ * access to a calendar entry should prefer `findEntryFile`.
+ */
+import type { DeskworkConfig } from './config.ts';
+import type { ContentIndex } from './content-index.ts';
+import type { Platform } from './types.ts';
+/**
+ * Resolve a user-supplied site argument to a configured site slug.
+ *
+ * An empty / null / undefined value falls back to `config.defaultSite`.
+ * An unknown value throws with the list of configured sites.
+ */
+export declare function resolveSite(config: DeskworkConfig, site: string | null | undefined): string;
+/** Absolute path to the site's editorial calendar file. */
+export declare function resolveCalendarPath(projectRoot: string, config: DeskworkConfig, site?: string | null): string;
+/** Absolute path to the site's channels file, or undefined when the site declares none. */
+export declare function resolveChannelsPath(projectRoot: string, config: DeskworkConfig, site?: string | null): string | undefined;
+/** Absolute path to the site's blog content directory. */
+export declare function resolveContentDir(projectRoot: string, config: DeskworkConfig, site?: string | null): string;
+/**
+ * Bare public hostname for the site (no protocol). Returns `undefined` for
+ * collections that aren't published as a website (no `host` configured).
+ * Callers needing a non-undefined value for display should fall back to the
+ * site slug; callers needing a real URL should throw if undefined.
+ */
+export declare function resolveSiteHost(config: DeskworkConfig, site?: string | null): string | undefined;
+/**
+ * Canonical public base URL for the site, with trailing slash. Throws when
+ * the collection has no `host` configured (i.e. is not published as a
+ * website) — callers that need a URL must guarantee the collection is a
+ * website-rendered one before calling.
+ */
+export declare function resolveSiteBaseUrl(config: DeskworkConfig, site?: string | null): string;
+/**
+ * Absolute path to the blog post markdown for a given slug.
+ *
+ * Resolution order (first match wins):
+ *   1. Explicit `filePath` argument — joined with the site's `contentDir`.
+ *      Used by the scaffolder when an explicit layout (`index` /
+ *      `readme` / `flat`) was requested.
+ *   2. The site's configured `blogFilenameTemplate` (default
+ *      `{slug}/index.md`). Audiocontrol-shaped flat blogs hit this path.
+ *
+ * Slug-only API for callers that don't have an entry id available
+ * (scaffold for not-yet-existent files, doctor's candidate search,
+ * legacy publish/iterate paths). Callers that already hold a calendar
+ * entry should prefer `findEntryFile` — it consults the content index
+ * first, falling back to this template-driven path only when no
+ * frontmatter binding exists yet.
+ */
+export declare function resolveBlogFilePath(projectRoot: string, config: DeskworkConfig, site: string | null | undefined, slug: string, filePath?: string): string;
+/**
+ * Absolute path to the per-post directory for a slug —
+ * `<contentDir>/<slug>/`. Used by features that co-locate per-post
+ * artifacts (scrapbook, feature images) regardless of whether the
+ * blog markdown lives at `<slug>/index.md` or as a flat `<slug>.md`.
+ *
+ * The directory is not guaranteed to exist. Callers that need it
+ * created should `mkdirSync({ recursive: true })`.
+ */
+export declare function resolveBlogPostDir(projectRoot: string, config: DeskworkConfig, site: string | null | undefined, slug: string): string;
+/**
+ * Resolve a calendar entry's file location via the content index.
+ *
+ * Refactor-proof: the binding is whatever file currently has matching
+ * frontmatter `id:`. When the index has no record (entry's file hasn't
+ * been bound yet — pre-doctor state) AND `legacyEntryForFallback` is
+ * supplied, falls back to the site's `blogFilenameTemplate` to preserve
+ * legacy behavior. Without that fallback hint, returns `undefined` so
+ * callers can decide how to surface the missing binding.
+ *
+ * Note: the returned path is what the index says — its existence on
+ * disk is implied (the index only records files it walked). The
+ * template fallback path may NOT exist on disk; callers that need
+ * existence guarantees should `existsSync` the result.
+ *
+ * @param projectRoot Absolute path to the deskwork project root.
+ * @param config Loaded deskwork config.
+ * @param site Site slug (or null/undefined for the default site).
+ * @param entryId Calendar entry's stable UUID.
+ * @param index Pre-built content index. When omitted, this function
+ *              builds one. The studio passes a per-request memoized
+ *              index; the CLI typically lets it build per call.
+ * @param legacyEntryForFallback When supplied, allows the slug-template
+ *              fallback for entries that haven't been bound to
+ *              frontmatter yet. Pass `{slug}` to opt in.
+ * @returns absolute path, or undefined if neither index nor template resolves.
+ */
+export declare function findEntryFile(projectRoot: string, config: DeskworkConfig, site: string | null | undefined, entryId: string, index?: ContentIndex, legacyEntryForFallback?: {
+    slug: string;
+}): string | undefined;
+/**
+ * Resolve the markdown file backing a calendar entry, preferring the
+ * UUID frontmatter binding (refactor-proof) and falling back to the
+ * site's slug-template only when no binding exists.
+ *
+ * Equivalent to the studio's `resolveLongformFilePath` but exposed as a
+ * top-level helper from `paths.ts` so CLI commands can use it without
+ * pulling in `review/` infrastructure. Always returns an absolute path
+ * (the slug-template fallback is unconditional); callers should
+ * `existsSync` if they need an existence guarantee.
+ *
+ * Precedence:
+ *   1. Content index — when `entryId` is supplied (and non-empty), look
+ *      up the file whose frontmatter `deskwork.id:` matches. Refactor-
+ *      proof: the binding follows the file regardless of slug rename or
+ *      directory relocation.
+ *   2. Slug-template fallback — when the index has no record (entry's
+ *      file isn't bound to frontmatter yet, e.g. pre-doctor / pre-ingest
+ *      state) or no `entryId` was supplied, fall back to
+ *      `resolveBlogFilePath(slug)`.
+ *
+ * @param projectRoot Absolute path to the deskwork project root.
+ * @param config Loaded deskwork config.
+ * @param site Site slug (or null/undefined for the default site).
+ * @param slug Calendar entry slug — used both as the legacy fallback
+ *             template input and as a hint for the slug-template fallback.
+ * @param entryId Calendar entry's stable UUID. When omitted or empty,
+ *                resolution falls straight through to the slug template.
+ * @param index Pre-built content index. When omitted, this function
+ *              builds one. Pass the per-request memoized index when
+ *              calling from the studio; let the CLI build per call.
+ */
+export declare function resolveEntryFilePath(projectRoot: string, config: DeskworkConfig, site: string | null | undefined, slug: string, entryId?: string, index?: ContentIndex): string;
+/**
+ * Resolve the markdown file path for a shortform draft.
+ *
+ *   <contentDir>/<entry-dir>/scrapbook/shortform/<platform>[-<channel>].md
+ *
+ * Platform is the lowercase Platform value. Channel (if present) is appended
+ * as `-<channel>`. Channel must validate against the kebab-case regex —
+ * deskwork stores channels as kebab-case strings throughout.
+ *
+ * The entry directory is resolved through `findEntryFile` (id-driven,
+ * refactor-proof) with slug-template fallback for legacy entries created
+ * pre-doctor. The slug-template fallback is intentional migration logic so
+ * pre-bind entries keep working.
+ *
+ * Forward-compatibility: every reference to the shortform file location
+ * goes through this function. Phase 20 (sandbox migration) redirects this
+ * single function; everything downstream (handlers, CLI, studio) works
+ * unchanged.
+ *
+ * @param projectRoot Absolute path to the deskwork project root.
+ * @param config Loaded deskwork config.
+ * @param site Site slug (or null/undefined for the default site).
+ * @param entry Calendar entry — `id` preferred, `slug` used both as the
+ *              legacy fallback and to identify the entry directory.
+ * @param platform Which distribution platform.
+ * @param channel Optional sub-channel (e.g. `synthdiy` for r/synthdiy).
+ *                Must be kebab-case.
+ * @param index Optional pre-built content index (per-request memoization).
+ * @returns absolute file path, or undefined when neither the index nor the
+ *          slug-template fallback resolves the entry's directory.
+ */
+export declare function resolveShortformFilePath(projectRoot: string, config: DeskworkConfig, site: string, entry: {
+    id?: string;
+    slug: string;
+}, platform: Platform, channel?: string, index?: ContentIndex): string | undefined;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

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