dorfl 0.14.1 → 0.14.3

package/src/slug-safety.ts

@@ -0,0 +1,83 @@
+/**
+ * The SAFE-SLUG character set, and the one sanitiser every slug-producing path
+ * shares.
+ *
+ * A slug is not just a label: it becomes a file name (`work/<folder>/<slug>.md`),
+ * part of a git ref (`work/<slug>`, `work/intake-task-<slug>`), a command-line
+ * argument (`dorfl advance "task:<slug>"`, one per CI matrix leg) and text in
+ * commit messages. Several producers draft slugs from content an outsider can
+ * influence: `intake` from an issue's title and thread, the triage and apply
+ * rungs from an agent verdict. Before this module the only transform was
+ * `paramCase`, which keeps `$(`, backticks, quotes, `;`, `|` and `/`, and the
+ * triage/ADR paths only `trim()`med, so a drafted `../x` escaped its folder.
+ *
+ * Two functions, two jobs:
+ *
+ *   - {@link toSafeSlug} is for PRODUCERS: it turns any drafted text into a slug
+ *     made only of ASCII letters, digits and single hyphens. Its output always
+ *     passes {@link isSafeSlug}.
+ *   - {@link isSafeSlug} is for CONSUMERS: the slug resolvers refuse any slug
+ *     outside the safe set, which covers slugs no producer here minted (a
+ *     frontmatter `slug:` a human or agent wrote by hand). It is deliberately a
+ *     little wider than what {@link toSafeSlug} emits (it also allows `.` and
+ *     `_` and mixed case) so every slug already in use in a real `work/` tree
+ *     keeps resolving: those characters are inert in a file name, a ref and a
+ *     quoted shell word. `..` is still refused (path traversal), as is a leading
+ *     `-` (it would read as a command-line option) or `.` (a hidden file), and so
+ *     is a `.lock` suffix (git refuses it in a ref component).
+ */
+
+/**
+ * The longest slug either function accepts. Real slugs in this repo top out
+ * around 105 characters; 120 leaves room without letting a drafted essay become
+ * a file name or ref component.
+ */
+export const MAX_SLUG_LENGTH = 120;
+
+/** Letters, digits, `.`, `_`, `-`; starts and ends with a letter or digit. */
+const SAFE_SLUG_RE = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/;
+
+/** Git refuses a ref component ending in `.lock` (its lock-file suffix). */
+const GIT_LOCK_SUFFIX_RE = /\.lock$/i;
+
+/**
+ * Whether `slug` is safe to use as a file name, a git ref component and a
+ * command-line argument (see the module doc for the exact set).
+ */
+export function isSafeSlug(slug: string): boolean {
+	return (
+		slug.length > 0 &&
+		slug.length <= MAX_SLUG_LENGTH &&
+		SAFE_SLUG_RE.test(slug) &&
+		!slug.includes('..') &&
+		!GIT_LOCK_SUFFIX_RE.test(slug)
+	);
+}
+
+/**
+ * Turn drafted text into a safe slug: accents are folded to their base letter,
+ * every run of anything other than an ASCII letter or digit becomes ONE hyphen,
+ * leading/trailing hyphens are dropped, and the result is capped at
+ * {@link MAX_SLUG_LENGTH}. Case is preserved (callers that want lower case, like
+ * `intake`, `paramCase` first). Returns `''` when nothing usable is left, so the
+ * caller's existing "no slug to derive" refusal fires instead of a junk name.
+ */
+export function toSafeSlug(input: string): string {
+	return input
+		.normalize('NFKD')
+		.replace(/[\u0300-\u036f]/g, '')
+		.replace(/[^A-Za-z0-9]+/g, '-')
+		.replace(/^-+|-+$/g, '')
+		.slice(0, MAX_SLUG_LENGTH)
+		.replace(/-+$/, '');
+}
+
+/**
+ * Keep a slug that is already safe EXACTLY as it is, and sanitise one that is
+ * not. The producers use this so every input that worked before still yields
+ * the same slug, and only an unsafe one changes.
+ */
+export function ensureSafeSlug(input: string): string {
+	const trimmed = input.trim();
+	return isSafeSlug(trimmed) ? trimmed : toSafeSlug(trimmed);
+}

package/src/triage-persist.ts

@@ -11,6 +11,7 @@ import {resolveSidecarIdentity, sidecarPathFor} from './sidecar.js';
 import type {TriageAutoKind} from './triage-gate.js';
 import {renderTaskBody, renderSpecBody} from './buildable-body.js';
 import {setFrontmatterMarker} from './frontmatter.js';
+import {ensureSafeSlug} from './slug-safety.js';
 
 /**
  * The engine-owned TRIAGE PERSIST (spec `advance-loop`, task `advance-rung-triage`,
@@ -433,7 +434,9 @@ export async function promoteObservation(
 	const note = options.note ?? (() => {});
 
 	const {slug: obsSlug} = resolveSidecarIdentity(item);
-	const newSlug = (options.newSlug ?? obsSlug).trim();
+	// The drafted slug comes from an agent verdict: an unsafe one (a `/`, `..`,
+	// shell metacharacters) is sanitised, a safe one is kept exactly as drafted.
+	const newSlug = ensureSafeSlug(options.newSlug ?? obsSlug);
 	const artifact = options.artifact ?? 'task';
 	if (newSlug === '') {
 		return {
@@ -460,13 +463,16 @@ export async function promoteObservation(
 	// review-nits back-pointer); this is the triage-promote lineage. Matching on this
 	// explicit field — not the slug — is what keeps an unrelated same-slug task from
 	// false-positiving into a benign skip.
+	// A drafted `stubContent` carries its own frontmatter, and the ledger reads
+	// `slug:` before the file name, so stamp the SAFE slug over whatever the
+	// draft said: otherwise a drafted `slug: ../x` would become the item's
+	// identity even though the file name was sanitised.
+	const drafted =
+		options.stubContent !== undefined
+			? setFrontmatterMarker(options.stubContent, 'slug', newSlug)
+			: buildPromotedBody(artifact, newSlug, readItem(cwd, itemPath, env));
 	const content = setFrontmatterMarker(
-		ensureTaskDispatchable(
-			artifact,
-			newSlug,
-			options.stubContent ??
-				buildPromotedBody(artifact, newSlug, readItem(cwd, itemPath, env)),
-		),
+		ensureTaskDispatchable(artifact, newSlug, drafted),
 		'promotedFrom',
 		item,
 	);

package/src/verify-workflow-template.ts

@@ -21,7 +21,9 @@
  * trigger surface — the forward seam the spec's Applied Answers q3 names.
  */
 
+import {ACTION_PINS, pinnedUses} from './install-ci-action-pins.js';
 import type {ResolvedCIConfig} from './install-ci-core.js';
+import {shouldDropCheckoutCredentials} from './install-ci-core.js';
 
 /**
  * The required-status-check CONTEXT install-ci sets via branch protection AND the
@@ -47,7 +49,18 @@ export const VERIFY_WORKFLOW_PATH = 'workflows/verify.yml';
  * so the GitHub check it produces matches the required-status `context` install-ci
  * configures on `main` — by construction, not by hand-typed agreement.
  */
-export function generateVerifyWorkflow(_config: ResolvedCIConfig): string {
+export function generateVerifyWorkflow(config: ResolvedCIConfig): string {
+	// `persist-credentials: false` ONLY on a repo KNOWN to be public (see
+	// {@link shouldDropCheckoutCredentials}): this job has `contents: read`, so
+	// the persisted token can only ever read, and on a public repo reads need
+	// no token. Unknown / private / internal ⇒ today's checkout, unchanged.
+	const checkoutCredentials = shouldDropCheckoutCredentials(config)
+		? `
+          # Public repository: every git read works without a token, and this
+          # job cannot push, so do not leave the token in .git/config for later
+          # steps (the project-setup hook's installs, the gate) to read.
+          persist-credentials: false`
+		: '';
 	return `\
 # dorfl — the VERIFY workflow (Tier-1 GitHub ceiling; spec
 # land-time-reverify-and-parallel-merge-ceiling, task
@@ -100,9 +113,9 @@ jobs:
   ${VERIFY_CHECK_CONTEXT}:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: ${pinnedUses(ACTION_PINS.checkout)}
         with:
-          fetch-depth: 0
+          fetch-depth: 0${checkoutCredentials}
       - uses: ./.github/actions/dorfl-setup
       - name: run the repo verify gate
         run: dorfl verify