@schnick371/devsteps-shared 1.1.0-next.4 → 2.0.0-next.1

package/dist/core/compass.js

@@ -0,0 +1,207 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * The compass block (EPIC-059, design v6.1 §3): what applies to one story, bug, feature or
+ * spike, built from its implements chain — the top item's constraint and out-of-scope lines,
+ * tags and working rules, and the decisions and questions linked to the chain — cut to about
+ * 10 lines and 400 tokens. The order is DEC-019: the decisions and questions linked to the item
+ * and its parent story or feature, then at most four constraint and three out-of-scope lines,
+ * then the decisions and questions of the rest of the chain. A task gets a one-line summary.
+ * An item without a chain is its own source (STORY-487): a parentless story shows its own
+ * constraint and out-of-scope lines and counts its own working rules.
+ */
+import { EisenhowerQuadrant } from '../schemas/index.js';
+import { parseItemId } from '../utils/index.js';
+import { linkedDecisionsAndQuestions, walkCompassChain, } from './compass-chain.js';
+import { compassTokens } from './compass-render.js';
+import { isDeviation } from './decision-question.js';
+import { DECISION_STATUSES, QUESTION_STATUSES } from './decision-question-status.js';
+import { findEpicSection, sectionLines } from './epic-sections.js';
+import { readItem, readItemMetadata } from './item-store.js';
+/** The types whose `get` returns the full block. */
+export const COMPASS_BLOCK_TYPES = ['story', 'bug', 'feature', 'spike'];
+/** The ranked facts a block shows before its "+N more" line. */
+export const COMPASS_MAX_FACTS = 10;
+/** The source's constraint lines a block shows at most; the rest count in "+N more". */
+export const COMPASS_MAX_CONSTRAINTS = 4;
+/** The source's out-of-scope lines a block shows at most; the rest count in "+N more". */
+export const COMPASS_MAX_OUT_OF_SCOPE = 3;
+/** The size a block stays within, in tokens counted as characters / 4 (EPIC-059 constraint 3). */
+export const COMPASS_TOKEN_BUDGET = 400;
+const SOURCE_TITLE_MAX = 60;
+const TEXT_MAX = 140;
+const CHECK_MAX = 100;
+const TITLE_MAX = 100;
+const SUMMARY_IDS = 5;
+/** The parent types whose linked decisions and questions rank with the item's own (DEC-019). */
+const LEADING_PARENT_TYPES = ['story', 'feature'];
+function clip(text, max) {
+    return text.length <= max ? text : `${text.slice(0, max - 1).trimEnd()}…`;
+}
+function sourceOf(devstepsDir, top) {
+    const source = {
+        id: top.id,
+        title: clip(top.title, SOURCE_TITLE_MAX),
+        status: top.status,
+    };
+    const description = readItem(devstepsDir, top.id).description;
+    const lines = (key) => sectionLines(findEpicSection(description, key)?.body ?? '');
+    if (top.tags.length > 0)
+        source.tags = [...top.tags];
+    const rules = lines('working-rules').length;
+    if (rules > 0)
+        source.working_rules = rules;
+    const constraints = lines('constraints').map((line) => ({
+        kind: 'constraint',
+        text: clip(line.text, TEXT_MAX),
+        ...(line.check ? { check: clip(line.check, CHECK_MAX) } : {}),
+    }));
+    const outOfScope = lines('out-of-scope').map((line) => ({ kind: 'out-of-scope', text: clip(line.text, TEXT_MAX) }));
+    return { source, constraints, outOfScope };
+}
+/** A linked decision in review or done, or question in draft, with its rank; else undefined. */
+function rankedRecord(record) {
+    const { metadata, blocks } = record;
+    const { id, status } = metadata;
+    const urgency = EisenhowerQuadrant.options.indexOf(metadata.eisenhower);
+    const base = {
+        urgency: urgency < 0 ? EisenhowerQuadrant.options.length : urgency,
+        updated: metadata.updated,
+        number: parseItemId(id)?.number ?? 0,
+    };
+    const title = clip(metadata.title, TITLE_MAX);
+    if (metadata.type === 'question' && status === 'draft') {
+        const meaning = QUESTION_STATUSES.draft ?? status;
+        const fact = blocks
+            ? { kind: 'question', id, status, meaning, blocks, title }
+            : { kind: 'question', id, status, meaning, title };
+        return { ...base, fact, tier: blocks ? 0 : 2 };
+    }
+    if (metadata.type !== 'decision' || (status !== 'review' && status !== 'done'))
+        return undefined;
+    const meaning = DECISION_STATUSES[status] ?? status;
+    const deviation = isDeviation(metadata);
+    const fact = deviation
+        ? { kind: 'decision', id, status, meaning, deviation: true, title }
+        : { kind: 'decision', id, status, meaning, title };
+    return { ...base, fact, tier: deviation && status === 'review' ? 1 : 3 };
+}
+/**
+ * Blocking questions, deviations in review and other open questions by urgency, then newest;
+ * the remaining decisions newest first.
+ */
+function compareRanked(a, b) {
+    if (a.tier !== b.tier)
+        return a.tier - b.tier;
+    if (a.tier < 3 && a.urgency !== b.urgency)
+        return a.urgency - b.urgency;
+    if (a.updated !== b.updated)
+        return a.updated < b.updated ? 1 : -1;
+    return b.number - a.number;
+}
+function rankedFacts(records) {
+    return records
+        .flatMap((record) => rankedRecord(record) ?? [])
+        .sort(compareRanked)
+        .map((entry) => entry.fact);
+}
+/**
+ * The chain items whose decisions and questions lead the block (DEC-019): the item, and its
+ * first implements parent when that parent is a story or feature.
+ */
+function leadingDepth(chain, relation) {
+    const parent = chain[1];
+    return parent && !relation && LEADING_PARENT_TYPES.includes(parent.type) ? 2 : 1;
+}
+function gather(devstepsDir, item) {
+    const { items: chain, relation } = walkCompassChain(devstepsDir, item);
+    const top = chain[chain.length - 1];
+    const { source, constraints, outOfScope } = sourceOf(devstepsDir, top);
+    const linked = linkedDecisionsAndQuestions(devstepsDir, chain);
+    const leading = leadingDepth(chain, relation);
+    const ranked = [
+        ...rankedFacts(linked.filter((record) => record.depth < leading)),
+        ...constraints.slice(0, COMPASS_MAX_CONSTRAINTS),
+        ...outOfScope.slice(0, COMPASS_MAX_OUT_OF_SCOPE),
+        ...rankedFacts(linked.filter((record) => record.depth >= leading)),
+    ];
+    const held = [
+        ...constraints.slice(COMPASS_MAX_CONSTRAINTS),
+        ...outOfScope.slice(COMPASS_MAX_OUT_OF_SCOPE),
+    ];
+    const via = chain.slice(1, -1).map((member) => member.id);
+    const route = {
+        ...(via.length > 0 ? { via } : {}),
+        ...(relation ? { relation } : {}),
+    };
+    return { chain, source, ...route, ranked, held };
+}
+function withFacts(gathered, kept) {
+    const { source, via, relation, ranked, held } = gathered;
+    const left = ranked.length - kept + held.length;
+    return {
+        source,
+        ...(via ? { via } : {}),
+        ...(relation ? { relation } : {}),
+        facts: ranked.slice(0, kept),
+        ...(left > 0 ? { more: { count: left, trace: source.id } } : {}),
+    };
+}
+/**
+ * The block, cut to the fact cap and then, from the lowest priority up, to the token budget. An
+ * item that is its own source gets a block only for facts or working rules, never for tags alone.
+ */
+function compassBlock(gathered) {
+    const own = gathered.chain.length === 1;
+    if (own && gathered.ranked.length === 0 && !gathered.source.working_rules)
+        return undefined;
+    let kept = Math.min(gathered.ranked.length, COMPASS_MAX_FACTS);
+    let block = withFacts(gathered, kept);
+    while (kept > 0 && compassTokens(block) > COMPASS_TOKEN_BUDGET) {
+        kept -= 1;
+        block = withFacts(gathered, kept);
+    }
+    return block;
+}
+function compassSummary(gathered) {
+    const counts = {};
+    for (const fact of [...gathered.ranked, ...gathered.held]) {
+        counts[fact.kind] = (counts[fact.kind] ?? 0) + 1;
+    }
+    if (gathered.source.working_rules)
+        counts['working-rules'] = gathered.source.working_rules;
+    if (Object.keys(counts).length === 0)
+        return undefined;
+    const ids = gathered.ranked.flatMap((fact) => fact.kind === 'question' || fact.kind === 'decision' ? [fact.id] : []);
+    const full = gathered.chain.slice(1).find((member) => COMPASS_BLOCK_TYPES.includes(member.type));
+    const { via, relation } = gathered;
+    return {
+        source: gathered.source.id,
+        ...(via ? { via } : {}),
+        ...(relation ? { relation } : {}),
+        counts,
+        ids: ids.slice(0, SUMMARY_IDS),
+        ...(ids.length > SUMMARY_IDS ? { more_ids: ids.length - SUMMARY_IDS } : {}),
+        ...(full ? { full: full.id } : {}),
+    };
+}
+/**
+ * The compass of one item: the block for a story, bug, feature or spike, the summary line for
+ * a task, and undefined for every other type, for an unknown item and when nothing applies.
+ */
+export function buildCompass(devstepsDir, itemId) {
+    let item;
+    try {
+        item = readItemMetadata(devstepsDir, itemId).metadata;
+    }
+    catch {
+        return undefined;
+    }
+    if (item.type === 'task')
+        return compassSummary(gather(devstepsDir, item));
+    if (!COMPASS_BLOCK_TYPES.includes(item.type))
+        return undefined;
+    return compassBlock(gather(devstepsDir, item));
+}
+//# sourceMappingURL=compass.js.map

package/dist/core/compass.js.map

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

package/dist/core/config.d.ts

@@ -11,4 +11,15 @@ import type { DevStepsConfig } from '../schemas/index.js';
  * Follows same pattern as getItem() for consistency
  */
 export declare function getConfig(devstepsDir: string): Promise<DevStepsConfig>;
+/**
+ * Validate an author value before anything is created. `init` calls this first so
+ * a rejected project leaves no half-built `.devsteps/` directory behind.
+ */
+export declare function assertValidAuthor(author: string | undefined, source: string): void;
+/**
+ * Validate a configuration about to be written. `init` runs this before creating
+ * config.json so that an invalid `default_author` cannot be propagated into every
+ * item created afterwards — the failure mode behind a customer workspace incident.
+ */
+export declare function assertValidConfig(config: unknown): DevStepsConfig;
 //# sourceMappingURL=config.d.ts.map

package/dist/core/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;GAGG;AACH,wBAAsB,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAc5E"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAI1D;;;GAGG;AACH,wBAAsB,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAmB5E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAQlF;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,cAAc,CAMjE"}

package/dist/core/config.js

@@ -7,6 +7,9 @@
  */
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { z } from 'zod';
+import { DevStepsConfig as DevStepsConfigSchema } from '../schemas/index.js';
+import { describeZodIssues, ItemValidationError } from './item-validation.js';
 /**
  * Core business logic for loading project configuration
  * Follows same pattern as getItem() for consistency
@@ -19,7 +22,37 @@ export async function getConfig(devstepsDir) {
     if (!existsSync(configPath)) {
         throw new Error('Configuration file not found. Project may be corrupted.');
     }
+    // Deliberately tolerant: a project whose config.json violates the schema must
+    // still be diagnosable (`doctor`, `list`, `status`) instead of being locked out
+    // by the very loader that every command depends on. New values are rejected at
+    // the writing end — `assertValidConfig` below on init, and the item write guard
+    // when an invalid `default_author` would reach an item (STORY-382 / BUG-115).
     const config = JSON.parse(readFileSync(configPath, 'utf-8'));
     return config;
 }
+/**
+ * Validate an author value before anything is created. `init` calls this first so
+ * a rejected project leaves no half-built `.devsteps/` directory behind.
+ */
+export function assertValidAuthor(author, source) {
+    if (author === undefined)
+        return;
+    const parsed = z.string().email().safeParse(author);
+    if (parsed.success)
+        return;
+    const issue = `${source} has an invalid format: "${author}" — ${parsed.error.issues[0]?.message ?? 'invalid value'}`;
+    throw new ItemValidationError(`Cannot use this author: ${issue}`, [issue]);
+}
+/**
+ * Validate a configuration about to be written. `init` runs this before creating
+ * config.json so that an invalid `default_author` cannot be propagated into every
+ * item created afterwards — the failure mode behind a customer workspace incident.
+ */
+export function assertValidConfig(config) {
+    const parsed = DevStepsConfigSchema.safeParse(config);
+    if (parsed.success)
+        return parsed.data;
+    const issues = describeZodIssues(parsed.error.issues, config);
+    throw new ItemValidationError(`Cannot write config.json: ${issues.join('; ')}`, issues);
+}
 //# sourceMappingURL=config.js.map

package/dist/core/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,WAAmB;IACjD,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACvE,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC;IAEpD,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;IAC7E,CAAC;IAED,MAAM,MAAM,GAAmB,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;IAE7E,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,cAAc,IAAI,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE9E;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,WAAmB;IACjD,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACvE,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC;IAEpD,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;IAC7E,CAAC;IAED,8EAA8E;IAC9E,gFAAgF;IAChF,+EAA+E;IAC/E,gFAAgF;IAChF,8EAA8E;IAC9E,MAAM,MAAM,GAAmB,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;IAE7E,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAA0B,EAAE,MAAc;IAC1E,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO;IAEjC,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACpD,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO;IAE3B,MAAM,KAAK,GAAG,GAAG,MAAM,4BAA4B,MAAM,OAAO,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,IAAI,eAAe,EAAE,CAAC;IACrH,MAAM,IAAI,mBAAmB,CAAC,2BAA2B,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAe;IAC/C,MAAM,MAAM,GAAG,oBAAoB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACtD,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC;IAEvC,MAAM,MAAM,GAAG,iBAAiB,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9D,MAAM,IAAI,mBAAmB,CAAC,6BAA6B,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;AAC1F,CAAC"}

package/dist/core/context-items.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Item-derived context data: counts, recent updates, active items, key paths.
+ *
+ * Reads through `listItems`, which the item store serves from memory once warm
+ * (STORY-426). The legacy `.devsteps/index.json` is renamed away at migration, and
+ * reading it here reported an empty project on every migrated workspace (BUG-126).
+ *
+ * @see STORY-121 Layered AI Context Auto-Delivery
+ * @see BUG-126 context reads legacy index.json
+ */
+export interface ItemCounts {
+    total: number;
+    by_type: Record<string, number>;
+    by_status: Record<string, number>;
+}
+export interface RecentUpdate {
+    id: string;
+    type: string;
+    title: string;
+    updated: string;
+}
+/** Non-terminal item as the standard context level reports it. */
+export interface ActiveItemSummary {
+    id: string;
+    type: string;
+    title: string;
+    status: string;
+    updated: string;
+    affected_paths?: string[];
+}
+interface ContextItem {
+    id: string;
+    type: string;
+    title: string;
+    status: string;
+    updated: string;
+}
+/**
+ * Load every item's summary. The item store validates each file's stamp, so a
+ * warm call costs a stat pass and the counts are always current — no TTL cache
+ * sits in front of it any more, because the by-status directory that used to
+ * anchor one no longer exists.
+ */
+export declare function loadContextItems(devstepsDir: string): Promise<ContextItem[]>;
+/** Item counts by type and status. */
+export declare function getItemCounts(devstepsDir: string): Promise<ItemCounts>;
+/** The ten most recently updated items of the last `days` days. */
+export declare function getRecentUpdates(devstepsDir: string, days: number): Promise<RecentUpdate[]>;
+/**
+ * Every non-terminal item, newest first. In-progress items carry their
+ * `affected_paths`, read from the item file because the list projection omits
+ * them; the WIP limit keeps that read bounded.
+ */
+export declare function getActiveItemsSummary(devstepsDir: string): Promise<ActiveItemSummary[]>;
+/** Unique affected paths of in-progress items, first ten. */
+export declare function collectKeyPaths(items: ActiveItemSummary[]): string[];
+export {};
+//# sourceMappingURL=context-items.d.ts.map

package/dist/core/context-items.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-items.d.ts","sourceRoot":"","sources":["../../src/core/context-items.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,kEAAkE;AAClE,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,UAAU,WAAW;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AASD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAyBlF;AAMD,sCAAsC;AACtC,wBAAsB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAU5E;AAED,mEAAmE;AACnE,wBAAsB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CASjG;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAe7F;AAED,6DAA6D;AAC7D,wBAAgB,eAAe,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,MAAM,EAAE,CAYpE"}

package/dist/core/context-items.js

@@ -0,0 +1,111 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Item-derived context data: counts, recent updates, active items, key paths.
+ *
+ * Reads through `listItems`, which the item store serves from memory once warm
+ * (STORY-426). The legacy `.devsteps/index.json` is renamed away at migration, and
+ * reading it here reported an empty project on every migrated workspace (BUG-126).
+ *
+ * @see STORY-121 Layered AI Context Auto-Delivery
+ * @see BUG-126 context reads legacy index.json
+ */
+import { getItem } from './get.js';
+import { listItems } from './list.js';
+const TERMINAL_STATUSES = new Set(['done', 'cancelled', 'obsolete']);
+const RECENT_LIMIT = 10;
+const KEY_PATH_LIMIT = 10;
+/** One scan per workspace at a time: quick and standard fan out into three readers. */
+const inFlight = new Map();
+/**
+ * Load every item's summary. The item store validates each file's stamp, so a
+ * warm call costs a stat pass and the counts are always current — no TTL cache
+ * sits in front of it any more, because the by-status directory that used to
+ * anchor one no longer exists.
+ */
+export async function loadContextItems(devstepsDir) {
+    const pending = inFlight.get(devstepsDir);
+    if (pending)
+        return pending;
+    const load = (async () => {
+        let items = [];
+        try {
+            const result = await listItems(devstepsDir, {});
+            items = result.items.map((i) => ({
+                id: i.id,
+                type: i.type,
+                title: i.title,
+                status: i.status,
+                updated: i.updated,
+            }));
+        }
+        catch {
+            // Not initialized: an empty project is the honest answer.
+        }
+        finally {
+            inFlight.delete(devstepsDir);
+        }
+        return items;
+    })();
+    inFlight.set(devstepsDir, load);
+    return load;
+}
+function byUpdatedDesc(a, b) {
+    return new Date(b.updated).getTime() - new Date(a.updated).getTime();
+}
+/** Item counts by type and status. */
+export async function getItemCounts(devstepsDir) {
+    const items = await loadContextItems(devstepsDir);
+    const counts = { total: items.length, by_type: {}, by_status: {} };
+    for (const item of items) {
+        counts.by_type[item.type] = (counts.by_type[item.type] || 0) + 1;
+        counts.by_status[item.status] = (counts.by_status[item.status] || 0) + 1;
+    }
+    return counts;
+}
+/** The ten most recently updated items of the last `days` days. */
+export async function getRecentUpdates(devstepsDir, days) {
+    const items = await loadContextItems(devstepsDir);
+    const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
+    return items
+        .filter((item) => new Date(item.updated).getTime() > cutoff)
+        .sort(byUpdatedDesc)
+        .slice(0, RECENT_LIMIT)
+        .map(({ id, type, title, updated }) => ({ id, type, title, updated }));
+}
+/**
+ * Every non-terminal item, newest first. In-progress items carry their
+ * `affected_paths`, read from the item file because the list projection omits
+ * them; the WIP limit keeps that read bounded.
+ */
+export async function getActiveItemsSummary(devstepsDir) {
+    const items = await loadContextItems(devstepsDir);
+    const active = items.filter((item) => !TERMINAL_STATUSES.has(item.status)).sort(byUpdatedDesc);
+    return Promise.all(active.map(async (item) => {
+        if (item.status !== 'in-progress')
+            return { ...item };
+        try {
+            const { metadata } = await getItem(devstepsDir, item.id);
+            return { ...item, affected_paths: metadata.affected_paths };
+        }
+        catch {
+            return { ...item };
+        }
+    }));
+}
+/** Unique affected paths of in-progress items, first ten. */
+export function collectKeyPaths(items) {
+    const seen = new Set();
+    for (const item of items) {
+        if (item.status !== 'in-progress')
+            continue;
+        for (const p of item.affected_paths ?? []) {
+            seen.add(p);
+            if (seen.size >= KEY_PATH_LIMIT)
+                return [...seen];
+        }
+    }
+    return [...seen];
+}
+//# sourceMappingURL=context-items.js.map

package/dist/core/context-items.js.map

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

package/dist/core/context-render.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Text renderers for project context: the plain-text form the MCP resource and
+ * prompts embed, and the PROJECT.md generator behind `devsteps context generate`.
+ *
+ * @see STORY-121 TASK-272, TASK-275
+ */
+import { type ContextResponse } from './context.js';
+/**
+ * Format a ContextResponse as readable plain text for embedding in AI prompts
+ * (used by MCP resource devsteps://project-context).
+ * @see STORY-121 TASK-275
+ */
+export declare function formatContextAsText(ctx: ContextResponse): string;
+/**
+ * Generate PROJECT.md content from live project state.
+ * Used by `devsteps context generate` CLI command.
+ * @see STORY-121 TASK-272
+ */
+export declare function generateProjectMd(projectDir: string, devstepsDir: string): Promise<string>;
+//# sourceMappingURL=context-render.d.ts.map

package/dist/core/context-render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-render.d.ts","sourceRoot":"","sources":["../../src/core/context-render.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAGrE;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,CAoEhE;AACD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAyJhG"}