chore: consolidate new foundation and archive v1 (#1495)
This commit is contained in:
@@ -0,0 +1,160 @@
|
||||
import { Command } from 'commander';
|
||||
|
||||
import { PrdService } from './service.js';
|
||||
import { runPrdWizard } from './wizard.js';
|
||||
|
||||
interface InitCommandOptions {
|
||||
readonly name: string;
|
||||
readonly project: string;
|
||||
readonly template?: 'software' | 'feature' | 'spike';
|
||||
}
|
||||
|
||||
interface ListCommandOptions {
|
||||
readonly project: string;
|
||||
}
|
||||
|
||||
interface ShowCommandOptions {
|
||||
readonly project: string;
|
||||
readonly id?: string;
|
||||
}
|
||||
|
||||
interface ImportCommandOptions {
|
||||
readonly project: string;
|
||||
readonly file: string;
|
||||
readonly acceptSuccessor?: boolean;
|
||||
}
|
||||
|
||||
interface ExportCommandOptions {
|
||||
readonly project: string;
|
||||
readonly id?: string;
|
||||
readonly out?: string;
|
||||
}
|
||||
|
||||
function serviceFor(project: string): PrdService {
|
||||
return new PrdService({ projectPath: project });
|
||||
}
|
||||
|
||||
export function buildPrdyCli(): Command {
|
||||
const program = new Command();
|
||||
program.name('mosaic').description('Mosaic CLI').exitOverride();
|
||||
|
||||
const prdy = program.command('prdy').description('PRD wizard commands');
|
||||
|
||||
prdy
|
||||
.command('init')
|
||||
.description('Create a PRD document')
|
||||
.requiredOption('--name <name>', 'PRD name')
|
||||
.requiredOption('--project <path>', 'Project path')
|
||||
.option('--template <template>', 'Template (software|feature|spike)')
|
||||
.action(async (options: InitCommandOptions) => {
|
||||
const doc = process.stdout.isTTY
|
||||
? await runPrdWizard({
|
||||
name: options.name,
|
||||
projectPath: options.project,
|
||||
template: options.template,
|
||||
interactive: true,
|
||||
})
|
||||
: await serviceFor(options.project).create({
|
||||
name: options.name,
|
||||
template: options.template,
|
||||
});
|
||||
|
||||
console.log(
|
||||
JSON.stringify(
|
||||
{
|
||||
ok: true,
|
||||
id: doc.id,
|
||||
title: doc.title,
|
||||
status: doc.status,
|
||||
version: doc.version,
|
||||
projectPath: doc.projectPath,
|
||||
},
|
||||
null,
|
||||
2,
|
||||
),
|
||||
);
|
||||
});
|
||||
|
||||
prdy
|
||||
.command('list')
|
||||
.description('List PRD documents for a project')
|
||||
.requiredOption('--project <path>', 'Project path')
|
||||
.action(async (options: ListCommandOptions) => {
|
||||
const docs = await serviceFor(options.project).list();
|
||||
console.log(JSON.stringify(docs, null, 2));
|
||||
});
|
||||
|
||||
prdy
|
||||
.command('show')
|
||||
.description('Show a PRD document')
|
||||
.requiredOption('--project <path>', 'Project path')
|
||||
.option('--id <id>', 'PRD document id')
|
||||
.action(async (options: ShowCommandOptions) => {
|
||||
const doc = await serviceFor(options.project).get(options.id);
|
||||
console.log(JSON.stringify(doc, null, 2));
|
||||
});
|
||||
|
||||
prdy
|
||||
.command('import')
|
||||
.description('Import a YAML PRD document (validated; conflicts propose a successor)')
|
||||
.requiredOption('--project <path>', 'Project path')
|
||||
.requiredOption('--file <file>', 'Path to YAML PRD document')
|
||||
.option('--accept-successor', 'Accept a conflicted import as the next version')
|
||||
.action(async (options: ImportCommandOptions) => {
|
||||
const service = serviceFor(options.project);
|
||||
const input = { filePath: options.file };
|
||||
|
||||
if (options.acceptSuccessor) {
|
||||
const successor = await service.acceptSuccessor(input);
|
||||
console.log(
|
||||
JSON.stringify(
|
||||
{
|
||||
ok: true,
|
||||
outcome: 'successor-accepted',
|
||||
id: successor.id,
|
||||
version: successor.version,
|
||||
},
|
||||
null,
|
||||
2,
|
||||
),
|
||||
);
|
||||
return;
|
||||
}
|
||||
|
||||
const result = await service.importDocument(input);
|
||||
console.log(
|
||||
JSON.stringify(
|
||||
{
|
||||
ok: true,
|
||||
outcome: result.kind,
|
||||
id: result.document.id,
|
||||
version: result.document.version,
|
||||
status: result.document.status,
|
||||
},
|
||||
null,
|
||||
2,
|
||||
),
|
||||
);
|
||||
});
|
||||
|
||||
prdy
|
||||
.command('export')
|
||||
.description('Render a PRD to a labeled generated-view Markdown file')
|
||||
.requiredOption('--project <path>', 'Project path')
|
||||
.option('--id <id>', 'PRD document id')
|
||||
.option('--out <path>', 'Output path (default docs/prdy/<id>.md)')
|
||||
.action(async (options: ExportCommandOptions) => {
|
||||
const result = await serviceFor(options.project).exportMarkdown({
|
||||
id: options.id,
|
||||
outPath: options.out,
|
||||
});
|
||||
console.log(JSON.stringify({ ok: true, filePath: result.filePath }, null, 2));
|
||||
});
|
||||
|
||||
return program;
|
||||
}
|
||||
|
||||
export async function runPrdyCli(argv: readonly string[] = process.argv): Promise<void> {
|
||||
const program = buildPrdyCli();
|
||||
await program.parseAsync(argv);
|
||||
}
|
||||
@@ -0,0 +1,35 @@
|
||||
// PrdService is the single authority surface for PRD documents. The raw store
|
||||
// writers (createPrd/savePrd) are deliberately NOT exported: every mutation
|
||||
// goes through the service so there is no second writer path.
|
||||
export { loadPrd, listPrds, parsePrdDocument } from './prd.js';
|
||||
export { runPrdWizard } from './wizard.js';
|
||||
export { buildPrdyCli, runPrdyCli } from './cli.js';
|
||||
export { BUILTIN_PRD_TEMPLATES, resolveTemplate } from './templates.js';
|
||||
export {
|
||||
PrdService,
|
||||
PRD_GENERATED_VIEW_LABEL,
|
||||
PrdError,
|
||||
PrdNotFoundError,
|
||||
PrdUpdateError,
|
||||
PrdImportInvalidError,
|
||||
PrdImportConflictError,
|
||||
} from './service.js';
|
||||
export type {
|
||||
PrdStatus,
|
||||
PrdTemplate,
|
||||
PrdTemplateSection,
|
||||
PrdSection,
|
||||
PrdMissionLinkage,
|
||||
PrdDocument,
|
||||
CreatePrdOptions,
|
||||
PrdServiceOptions,
|
||||
PrdCreateInput,
|
||||
PrdSectionPatch,
|
||||
PrdUpdateInput,
|
||||
PrdLinkMissionInput,
|
||||
PrdPlanForMissionInput,
|
||||
PrdExportInput,
|
||||
PrdExportResult,
|
||||
PrdImportInput,
|
||||
PrdImportResult,
|
||||
} from './types.js';
|
||||
@@ -0,0 +1,235 @@
|
||||
import { type Dirent, promises as fs } from 'node:fs';
|
||||
import os from 'node:os';
|
||||
import path from 'node:path';
|
||||
|
||||
import yaml from 'js-yaml';
|
||||
import { z } from 'zod';
|
||||
|
||||
import { resolveTemplate } from './templates.js';
|
||||
import type { CreatePrdOptions, PrdDocument } from './types.js';
|
||||
|
||||
const PRD_DIRECTORY = path.join('docs', 'prdy');
|
||||
const PRD_FILE_EXTENSIONS = new Set(['.yaml', '.yml']);
|
||||
|
||||
const prdSectionSchema = z.object({
|
||||
id: z.string().min(1),
|
||||
title: z.string().min(1),
|
||||
fields: z.record(z.string(), z.string()),
|
||||
});
|
||||
|
||||
const prdMissionLinkageSchema = z.object({
|
||||
missionId: z.string().min(1),
|
||||
missionVersion: z.string().min(1),
|
||||
prdVersion: z.number().int().min(1),
|
||||
requirementIds: z.array(z.string()),
|
||||
linkedAt: z.string().datetime(),
|
||||
});
|
||||
|
||||
const prdDocumentSchema = z.object({
|
||||
id: z.string().min(1),
|
||||
title: z.string().min(1),
|
||||
status: z.enum(['draft', 'review', 'approved', 'archived']),
|
||||
projectPath: z.string().min(1),
|
||||
template: z.string().min(1),
|
||||
// Defaults keep documents written by older prdy versions loadable.
|
||||
version: z.number().int().min(1).default(1),
|
||||
sections: z.array(prdSectionSchema),
|
||||
missions: z.array(prdMissionLinkageSchema).default([]),
|
||||
createdAt: z.string().datetime(),
|
||||
updatedAt: z.string().datetime(),
|
||||
});
|
||||
|
||||
/** YAML timestamp scalars are parsed as Date by some emitters — normalize to ISO strings. */
|
||||
function coerceTimestamps(value: unknown): unknown {
|
||||
if (value instanceof Date) {
|
||||
return value.toISOString();
|
||||
}
|
||||
if (Array.isArray(value)) {
|
||||
return value.map(coerceTimestamps);
|
||||
}
|
||||
if (typeof value === 'object' && value !== null) {
|
||||
return Object.fromEntries(
|
||||
Object.entries(value).map(([key, entry]) => [key, coerceTimestamps(entry)]),
|
||||
);
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
/** Validate an unknown value as a PRD document (throws zod errors on failure). */
|
||||
export function parsePrdDocument(value: unknown): PrdDocument {
|
||||
return prdDocumentSchema.parse(coerceTimestamps(value)) as PrdDocument;
|
||||
}
|
||||
|
||||
function expandHome(projectPath: string): string {
|
||||
if (!projectPath.startsWith('~')) {
|
||||
return projectPath;
|
||||
}
|
||||
|
||||
if (projectPath === '~') {
|
||||
return os.homedir();
|
||||
}
|
||||
|
||||
if (projectPath.startsWith('~/')) {
|
||||
return path.join(os.homedir(), projectPath.slice(2));
|
||||
}
|
||||
|
||||
return projectPath;
|
||||
}
|
||||
|
||||
function resolveProjectPath(projectPath: string): string {
|
||||
return path.resolve(expandHome(projectPath));
|
||||
}
|
||||
|
||||
function toSlug(value: string): string {
|
||||
return value
|
||||
.toLowerCase()
|
||||
.replace(/[^a-z0-9]+/g, '-')
|
||||
.replace(/^-+|-+$/g, '')
|
||||
.replace(/-{2,}/g, '-');
|
||||
}
|
||||
|
||||
function buildTimestamp(date: Date): { datePart: string; timePart: string } {
|
||||
const iso = date.toISOString();
|
||||
return {
|
||||
datePart: iso.slice(0, 10).replace(/-/g, ''),
|
||||
timePart: iso.slice(11, 19).replace(/:/g, ''),
|
||||
};
|
||||
}
|
||||
|
||||
function buildPrdId(name: string): string {
|
||||
const slug = toSlug(name);
|
||||
const { datePart, timePart } = buildTimestamp(new Date());
|
||||
return `${slug || 'prd'}-${datePart}-${timePart}`;
|
||||
}
|
||||
|
||||
function prdDirectory(projectPath: string): string {
|
||||
return path.join(projectPath, PRD_DIRECTORY);
|
||||
}
|
||||
|
||||
export { prdDirectory };
|
||||
|
||||
function prdFilePath(projectPath: string, id: string): string {
|
||||
return path.join(prdDirectory(projectPath), `${id}.yaml`);
|
||||
}
|
||||
|
||||
function isNodeErrorWithCode(error: unknown, code: string): boolean {
|
||||
return (
|
||||
typeof error === 'object' &&
|
||||
error !== null &&
|
||||
'code' in error &&
|
||||
(error as { code?: string }).code === code
|
||||
);
|
||||
}
|
||||
|
||||
async function writeFileAtomic(filePath: string, content: string): Promise<void> {
|
||||
const directory = path.dirname(filePath);
|
||||
await fs.mkdir(directory, { recursive: true });
|
||||
|
||||
const tempPath = path.join(
|
||||
directory,
|
||||
`.${path.basename(filePath)}.tmp-${process.pid}-${Date.now()}-${Math.random()
|
||||
.toString(16)
|
||||
.slice(2)}`,
|
||||
);
|
||||
|
||||
await fs.writeFile(tempPath, content, 'utf8');
|
||||
await fs.rename(tempPath, filePath);
|
||||
}
|
||||
|
||||
export async function createPrd(options: CreatePrdOptions): Promise<PrdDocument> {
|
||||
const resolvedProjectPath = resolveProjectPath(options.projectPath);
|
||||
const template = resolveTemplate(options.template);
|
||||
const now = new Date().toISOString();
|
||||
|
||||
const document: PrdDocument = {
|
||||
id: buildPrdId(options.name),
|
||||
title: options.name.trim(),
|
||||
status: 'draft',
|
||||
projectPath: resolvedProjectPath,
|
||||
template: template.id,
|
||||
version: 1,
|
||||
sections: template.sections.map((section) => ({
|
||||
id: section.id,
|
||||
title: section.title,
|
||||
fields: Object.fromEntries(section.fields.map((field) => [field, ''])),
|
||||
})),
|
||||
missions: [],
|
||||
createdAt: now,
|
||||
updatedAt: now,
|
||||
};
|
||||
|
||||
await savePrd(document);
|
||||
return document;
|
||||
}
|
||||
|
||||
export async function loadPrd(projectPath: string): Promise<PrdDocument> {
|
||||
const documents = await listPrds(projectPath);
|
||||
if (documents.length === 0) {
|
||||
const resolvedProjectPath = resolveProjectPath(projectPath);
|
||||
throw new Error(`No PRD documents found in ${prdDirectory(resolvedProjectPath)}`);
|
||||
}
|
||||
|
||||
return documents[0]!;
|
||||
}
|
||||
|
||||
export async function savePrd(doc: PrdDocument): Promise<void> {
|
||||
const normalized = prdDocumentSchema.parse({
|
||||
...doc,
|
||||
projectPath: resolveProjectPath(doc.projectPath),
|
||||
});
|
||||
|
||||
const filePath = prdFilePath(normalized.projectPath, normalized.id);
|
||||
const serialized = yaml.dump(normalized, {
|
||||
noRefs: true,
|
||||
sortKeys: false,
|
||||
lineWidth: 120,
|
||||
});
|
||||
|
||||
const content = serialized.endsWith('\n') ? serialized : `${serialized}\n`;
|
||||
await writeFileAtomic(filePath, content);
|
||||
}
|
||||
|
||||
export async function listPrds(projectPath: string): Promise<PrdDocument[]> {
|
||||
const resolvedProjectPath = resolveProjectPath(projectPath);
|
||||
const directory = prdDirectory(resolvedProjectPath);
|
||||
|
||||
let entries: Dirent[];
|
||||
try {
|
||||
entries = await fs.readdir(directory, { withFileTypes: true, encoding: 'utf8' });
|
||||
} catch (error) {
|
||||
if (isNodeErrorWithCode(error, 'ENOENT')) {
|
||||
return [];
|
||||
}
|
||||
|
||||
throw error;
|
||||
}
|
||||
|
||||
const documents: PrdDocument[] = [];
|
||||
|
||||
for (const entry of entries) {
|
||||
if (!entry.isFile()) {
|
||||
continue;
|
||||
}
|
||||
|
||||
const ext = path.extname(entry.name);
|
||||
if (!PRD_FILE_EXTENSIONS.has(ext)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
const filePath = path.join(directory, entry.name);
|
||||
const raw = await fs.readFile(filePath, 'utf8');
|
||||
|
||||
let parsed: unknown;
|
||||
try {
|
||||
parsed = yaml.load(raw);
|
||||
} catch (error) {
|
||||
throw new Error(`Failed to parse PRD file ${filePath}: ${String(error)}`);
|
||||
}
|
||||
|
||||
const document = parsePrdDocument(parsed);
|
||||
documents.push(document);
|
||||
}
|
||||
|
||||
documents.sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
|
||||
return documents;
|
||||
}
|
||||
@@ -0,0 +1,433 @@
|
||||
import { existsSync } from 'node:fs';
|
||||
import { mkdtemp, readFile, readdir, writeFile } from 'node:fs/promises';
|
||||
import os from 'node:os';
|
||||
import path from 'node:path';
|
||||
|
||||
import yaml from 'js-yaml';
|
||||
import { beforeEach, describe, expect, it } from 'vitest';
|
||||
|
||||
import {
|
||||
PRD_GENERATED_VIEW_LABEL,
|
||||
PrdImportConflictError,
|
||||
PrdImportInvalidError,
|
||||
PrdNotFoundError,
|
||||
PrdService,
|
||||
PrdUpdateError,
|
||||
} from './index.js';
|
||||
import type { PrdDocument } from './index.js';
|
||||
|
||||
// ── Helpers ──────────────────────────────────────────────────────────────────
|
||||
|
||||
let projectDir: string;
|
||||
|
||||
async function makeProject(): Promise<string> {
|
||||
return mkdtemp(path.join(os.tmpdir(), 'prdy-service-'));
|
||||
}
|
||||
|
||||
function service(): PrdService {
|
||||
return new PrdService({ projectPath: projectDir });
|
||||
}
|
||||
|
||||
function storeDir(): string {
|
||||
return path.join(projectDir, 'docs', 'prdy');
|
||||
}
|
||||
|
||||
/** Handcraft a full, schema-valid PRD document for import scenarios. */
|
||||
function importFixture(overrides: Partial<PrdDocument> = {}): PrdDocument {
|
||||
return {
|
||||
id: 'imported-prd-20260101-000000',
|
||||
title: 'Imported PRD',
|
||||
status: 'draft',
|
||||
projectPath: '/tmp/elsewhere',
|
||||
template: 'software',
|
||||
version: 1,
|
||||
sections: [
|
||||
{ id: 'introduction', title: 'Introduction', fields: { context: '', objective: '' } },
|
||||
{
|
||||
id: 'scope-non-goals',
|
||||
title: 'Scope / Non-Goals',
|
||||
fields: { inScope: '', outOfScope: '' },
|
||||
},
|
||||
],
|
||||
missions: [],
|
||||
createdAt: '2026-01-01T00:00:00.000Z',
|
||||
updatedAt: '2026-01-01T00:00:00.000Z',
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
async function writeImportFile(doc: PrdDocument): Promise<string> {
|
||||
const filePath = path.join(projectDir, `${doc.id}.import.yaml`);
|
||||
await writeFile(filePath, yaml.dump(doc), 'utf8');
|
||||
return filePath;
|
||||
}
|
||||
|
||||
beforeEach(async () => {
|
||||
projectDir = await makeProject();
|
||||
});
|
||||
|
||||
// ── Single authority store (AC: prdy path and mission path resolve to the
|
||||
// SAME store under docs/prdy/ with stable ids/versions) ────────────────────
|
||||
|
||||
describe('PrdService single authority store', () => {
|
||||
it('persists PRDs from the prdy path and the mission path into the same docs/prdy store', async () => {
|
||||
const direct = await service().create({ name: 'Direct PRD' });
|
||||
const viaMission = await service().planForMission({
|
||||
name: 'Mission PRD',
|
||||
missionId: 'mission-1',
|
||||
missionVersion: '2026-01-01T00:00:00.000Z',
|
||||
});
|
||||
|
||||
const files = await readdir(storeDir());
|
||||
expect(files).toContain(`${direct.id}.yaml`);
|
||||
expect(files).toContain(`${viaMission.id}.yaml`);
|
||||
|
||||
// A fresh service instance (new process equivalent) resolves both.
|
||||
const all = await service().list();
|
||||
expect(all.map((doc) => doc.id).sort()).toEqual([direct.id, viaMission.id].sort());
|
||||
|
||||
// Stable versions: creation is v1; linkage writes do not bump content version.
|
||||
expect((await service().get(direct.id)).version).toBe(1);
|
||||
expect((await service().get(viaMission.id)).version).toBe(1);
|
||||
});
|
||||
|
||||
it('round-trips documents through the store with identity intact', async () => {
|
||||
const created = await service().create({ name: 'Round Trip', template: 'feature' });
|
||||
const fresh = await service().get(created.id);
|
||||
|
||||
expect(fresh).toEqual(created);
|
||||
expect(fresh.id).toBe(created.id);
|
||||
expect(fresh.template).toBe('feature');
|
||||
expect(fresh.status).toBe('draft');
|
||||
});
|
||||
|
||||
it('throws a typed error for unknown ids and empty stores', async () => {
|
||||
await expect(service().get('nope')).rejects.toBeInstanceOf(PrdNotFoundError);
|
||||
await expect(service().get()).rejects.toBeInstanceOf(PrdNotFoundError);
|
||||
});
|
||||
});
|
||||
|
||||
// ── Mission linkage persistence (AC: linkage survives restart via fresh
|
||||
// service instances) ────────────────────────────────────────────────────────
|
||||
|
||||
describe('PrdService mission linkage', () => {
|
||||
it('persists linkage and reads it back from a fresh service instance', async () => {
|
||||
const created = await service().planForMission({
|
||||
name: 'Linked PRD',
|
||||
missionId: 'mission-42',
|
||||
missionVersion: '2026-02-03T04:05:06.000Z',
|
||||
requirementIds: ['FR-1', 'FR-2'],
|
||||
});
|
||||
|
||||
// Fresh instance — nothing in memory from the creating call.
|
||||
const links = await service().listMissionLinks(created.id);
|
||||
expect(links).toHaveLength(1);
|
||||
expect(links[0]).toMatchObject({
|
||||
missionId: 'mission-42',
|
||||
missionVersion: '2026-02-03T04:05:06.000Z',
|
||||
prdVersion: 1,
|
||||
requirementIds: ['FR-1', 'FR-2'],
|
||||
});
|
||||
|
||||
// Linkage is carried in the YAML authority file itself.
|
||||
const raw = await readFile(path.join(storeDir(), `${created.id}.yaml`), 'utf8');
|
||||
const persisted = yaml.load(raw) as PrdDocument;
|
||||
expect(persisted.missions[0]?.missionId).toBe('mission-42');
|
||||
expect(persisted.missions[0]?.requirementIds).toEqual(['FR-1', 'FR-2']);
|
||||
});
|
||||
|
||||
it('refreshes an existing linkage entry in place instead of duplicating', async () => {
|
||||
const created = await service().planForMission({
|
||||
name: 'Relink PRD',
|
||||
missionId: 'mission-7',
|
||||
missionVersion: 'v1',
|
||||
});
|
||||
|
||||
await service().update({
|
||||
id: created.id,
|
||||
sections: [{ id: 'introduction', fields: { objective: 'Ship it' } }],
|
||||
});
|
||||
|
||||
const relinked = await service().linkMission({
|
||||
prdId: created.id,
|
||||
missionId: 'mission-7',
|
||||
missionVersion: 'v2',
|
||||
requirementIds: ['NFR-1'],
|
||||
});
|
||||
|
||||
expect(relinked.missions).toHaveLength(1);
|
||||
expect(relinked.missions[0]).toMatchObject({ missionVersion: 'v2', prdVersion: 2 });
|
||||
});
|
||||
|
||||
it('does not bump the content version when writing linkage', async () => {
|
||||
const created = await service().create({ name: 'Stable Version' });
|
||||
const linked = await service().linkMission({
|
||||
prdId: created.id,
|
||||
missionId: 'm',
|
||||
missionVersion: 'v1',
|
||||
});
|
||||
expect(linked.version).toBe(1);
|
||||
});
|
||||
});
|
||||
|
||||
// ── Update semantics ──────────────────────────────────────────────────────────
|
||||
|
||||
describe('PrdService update', () => {
|
||||
it('applies section patches and bumps the content version', async () => {
|
||||
const created = await service().create({ name: 'Updatable' });
|
||||
const updated = await service().update({
|
||||
id: created.id,
|
||||
sections: [{ id: 'introduction', fields: { context: 'Some context', objective: 'Goal' } }],
|
||||
});
|
||||
|
||||
expect(updated.version).toBe(2);
|
||||
expect(updated.sections[0]?.fields).toMatchObject({
|
||||
context: 'Some context',
|
||||
objective: 'Goal',
|
||||
});
|
||||
expect((await service().get(created.id)).version).toBe(2);
|
||||
});
|
||||
|
||||
it('refuses unknown section ids with a typed error', async () => {
|
||||
const created = await service().create({ name: 'Strict' });
|
||||
await expect(
|
||||
service().update({ id: created.id, sections: [{ id: 'nope', fields: {} }] }),
|
||||
).rejects.toBeInstanceOf(PrdUpdateError);
|
||||
});
|
||||
});
|
||||
|
||||
// ── Markdown export is a labeled generated view, never authority ──────────────
|
||||
|
||||
describe('PrdService exportMarkdown', () => {
|
||||
it('writes a generated view carrying the label and source identity', async () => {
|
||||
const created = await service().create({ name: 'Exported PRD' });
|
||||
const result = await service().exportMarkdown({ id: created.id });
|
||||
|
||||
expect(result.filePath).toBe(path.join(storeDir(), `${created.id}.md`));
|
||||
expect(result.content).toContain(PRD_GENERATED_VIEW_LABEL);
|
||||
expect(result.content).toContain(`prd-id: ${created.id}`);
|
||||
expect(result.content).toContain('prd-version: 1');
|
||||
expect(result.content).toContain(`source-of-truth: docs/prdy/${created.id}.yaml`);
|
||||
});
|
||||
|
||||
it('reflects the current version after updates', async () => {
|
||||
const created = await service().create({ name: 'Versioned Export' });
|
||||
await service().update({
|
||||
id: created.id,
|
||||
sections: [{ id: 'introduction', fields: { objective: 'v2 goal' } }],
|
||||
});
|
||||
const result = await service().exportMarkdown({ id: created.id });
|
||||
expect(result.content).toContain('prd-version: 2');
|
||||
});
|
||||
|
||||
it('NEGATIVE CONTROL: mutating the exported Markdown cannot change the authority', async () => {
|
||||
const created = await service().create({ name: 'Guarded PRD' });
|
||||
const before = structuredClone(await service().get(created.id));
|
||||
|
||||
const result = await service().exportMarkdown({ id: created.id });
|
||||
await writeFile(
|
||||
result.filePath,
|
||||
`<!-- ${PRD_GENERATED_VIEW_LABEL} -->\n# FAKE\nprd-id: fake-id\nprd-version: 99\n`,
|
||||
'utf8',
|
||||
);
|
||||
|
||||
const after = await service().get(created.id);
|
||||
expect(after).toEqual(before);
|
||||
expect(after.version).toBe(1);
|
||||
expect(after.title).toBe(before.title);
|
||||
});
|
||||
|
||||
it('never parses Markdown files that sit in the store directory', async () => {
|
||||
const created = await service().create({ name: 'Decoy Guard' });
|
||||
|
||||
// A decoy .md file with invalid YAML must be invisible to the store.
|
||||
await writeFile(path.join(storeDir(), 'decoy.md'), 'not: [valid: yaml', 'utf8');
|
||||
// And a decoy .yaml-named Markdown body must not silently validate either.
|
||||
await service().exportMarkdown({ id: created.id });
|
||||
|
||||
const listed = await service().list();
|
||||
expect(listed.map((doc) => doc.id)).toEqual([created.id]);
|
||||
await expect(service().get(created.id)).resolves.toBeTruthy();
|
||||
});
|
||||
});
|
||||
|
||||
// ── Import: validated, conflict-aware, never silently merging ─────────────────
|
||||
|
||||
describe('PrdService importDocument', () => {
|
||||
it('creates a valid import through the service, as draft — validity is not approval', async () => {
|
||||
const filePath = await writeImportFile(importFixture({ status: 'approved' }));
|
||||
|
||||
const result = await service().importDocument({ filePath });
|
||||
|
||||
expect(result.kind).toBe('created');
|
||||
expect(result.document.id).toBe('imported-prd-20260101-000000');
|
||||
expect(result.document.status).toBe('draft'); // structural validity ≠ approval
|
||||
expect(result.document.version).toBe(1);
|
||||
|
||||
const persisted = await service().get('imported-prd-20260101-000000');
|
||||
expect(persisted.status).toBe('draft');
|
||||
|
||||
const files = await readdir(storeDir());
|
||||
expect(files).toContain('imported-prd-20260101-000000.yaml');
|
||||
});
|
||||
|
||||
it('reports identical content as a no-op without writing', async () => {
|
||||
const created = await service().create({ name: 'Existing PRD' });
|
||||
const before = await readFile(path.join(storeDir(), `${created.id}.yaml`), 'utf8');
|
||||
|
||||
const filePath = await writeImportFile(importFixture({ ...created }));
|
||||
const result = await service().importDocument({ filePath });
|
||||
|
||||
expect(result.kind).toBe('identical');
|
||||
const after = await readFile(path.join(storeDir(), `${created.id}.yaml`), 'utf8');
|
||||
expect(after).toBe(before);
|
||||
});
|
||||
|
||||
it('refuses a conflicting import with a typed error, a proposed successor, and untouched bytes', async () => {
|
||||
const existing = await service().create({ name: 'Authority PRD' });
|
||||
await service().linkMission({
|
||||
prdId: existing.id,
|
||||
missionId: 'mission-keep',
|
||||
missionVersion: 'v1',
|
||||
requirementIds: ['FR-0'],
|
||||
});
|
||||
const beforeBytes = await readFile(path.join(storeDir(), `${existing.id}.yaml`), 'utf8');
|
||||
|
||||
const divergent = importFixture({
|
||||
...existing,
|
||||
title: 'Divergent Title',
|
||||
sections: [
|
||||
{
|
||||
id: 'introduction',
|
||||
title: 'Introduction',
|
||||
fields: { context: 'changed', objective: '' },
|
||||
},
|
||||
],
|
||||
});
|
||||
const filePath = await writeImportFile(divergent);
|
||||
|
||||
const attempt = service().importDocument({ filePath });
|
||||
let caught: unknown;
|
||||
try {
|
||||
await attempt;
|
||||
} catch (error) {
|
||||
caught = error;
|
||||
}
|
||||
expect(caught).toBeInstanceOf(PrdImportConflictError);
|
||||
|
||||
const error = caught as PrdImportConflictError;
|
||||
expect(error.code).toBe('PRD_IMPORT_CONFLICT');
|
||||
expect(error.existing.id).toBe(existing.id);
|
||||
expect(error.proposal.version).toBe(existing.version + 1); // successor proposal
|
||||
expect(error.proposal.status).toBe('draft');
|
||||
|
||||
// Original authority content untouched on disk.
|
||||
const afterBytes = await readFile(path.join(storeDir(), `${existing.id}.yaml`), 'utf8');
|
||||
expect(afterBytes).toBe(beforeBytes);
|
||||
});
|
||||
|
||||
it('acceptSuccessor persists the proposal explicitly, carrying linkages forward', async () => {
|
||||
const existing = await service().create({ name: 'Successor Base' });
|
||||
await service().linkMission({
|
||||
prdId: existing.id,
|
||||
missionId: 'mission-keep',
|
||||
missionVersion: 'v1',
|
||||
});
|
||||
|
||||
const divergent = importFixture({
|
||||
...existing,
|
||||
title: 'Accepted Successor Title',
|
||||
});
|
||||
const filePath = await writeImportFile(divergent);
|
||||
|
||||
const successor = await service().acceptSuccessor({ filePath });
|
||||
expect(successor.id).toBe(existing.id);
|
||||
expect(successor.version).toBe(existing.version + 1);
|
||||
expect(successor.title).toBe('Accepted Successor Title');
|
||||
expect(successor.status).toBe('draft');
|
||||
expect(successor.missions.map((m) => m.missionId)).toEqual(['mission-keep']);
|
||||
|
||||
// Persisted for a fresh reader.
|
||||
const fresh = await service().get(existing.id);
|
||||
expect(fresh.version).toBe(2);
|
||||
expect(fresh.title).toBe('Accepted Successor Title');
|
||||
});
|
||||
|
||||
it('refuses structurally-invalid imports with a typed error and creates nothing', async () => {
|
||||
const cases: Array<{ name: string; body: string }> = [
|
||||
{ name: 'missing-title.yaml', body: yaml.dump({ id: 'x', status: 'draft' }) },
|
||||
{
|
||||
name: 'bad-status.yaml',
|
||||
body: yaml.dump(importFixture({ status: 'not-a-status' as PrdDocument['status'] })),
|
||||
},
|
||||
{
|
||||
name: 'bad-version.yaml',
|
||||
body: yaml.dump(importFixture({ version: 0 })),
|
||||
},
|
||||
{ name: 'not-yaml.yaml', body: '::: not yaml [\n - {' },
|
||||
];
|
||||
|
||||
for (const fixture of cases) {
|
||||
const filePath = path.join(projectDir, fixture.name);
|
||||
await writeFile(filePath, fixture.body, 'utf8');
|
||||
|
||||
await expect(service().importDocument({ filePath })).rejects.toBeInstanceOf(
|
||||
PrdImportInvalidError,
|
||||
);
|
||||
}
|
||||
|
||||
// Nothing was created: the authority store does not even exist yet.
|
||||
await expect(readdir(storeDir())).rejects.toMatchObject({ code: 'ENOENT' });
|
||||
});
|
||||
|
||||
it('acceptSuccessor refuses when there is no existing document to succeed', async () => {
|
||||
const filePath = await writeImportFile(importFixture());
|
||||
await expect(service().acceptSuccessor({ filePath })).rejects.toBeInstanceOf(PrdNotFoundError);
|
||||
});
|
||||
});
|
||||
|
||||
// ── No second writer: no code path reads exported Markdown back into authority ─
|
||||
|
||||
describe('no-second-writer invariant (source-level)', () => {
|
||||
// Resolve the package source dir whether vitest runs from the package root
|
||||
// (turbo/pnpm test) or from the worktree root.
|
||||
function resolveSrcDir(): string {
|
||||
const candidates = [path.resolve('src'), path.resolve('packages/prdy/src')];
|
||||
return candidates.find((dir) => existsSync(path.join(dir, 'service.ts'))) ?? candidates[0]!;
|
||||
}
|
||||
|
||||
const srcDir = resolveSrcDir();
|
||||
const sourceFiles = [
|
||||
'cli.ts',
|
||||
'index.ts',
|
||||
'prd.ts',
|
||||
'service.ts',
|
||||
'templates.ts',
|
||||
'types.ts',
|
||||
'wizard.ts',
|
||||
];
|
||||
|
||||
it('no source file in @mosaicstack/prdy reads a .md file', async () => {
|
||||
for (const file of sourceFiles) {
|
||||
const text = await readFile(path.join(srcDir, file), 'utf8');
|
||||
const readLines = text
|
||||
.split('\n')
|
||||
.map((line) => line.trim())
|
||||
.filter((line) => /readFile|readFileSync|createReadStream/.test(line));
|
||||
|
||||
for (const line of readLines) {
|
||||
expect(line.includes('.md'), `${file} reads a Markdown file: ${line}`).toBe(false);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
it('the mosaic prdy/mission adapters never read a .md file', async () => {
|
||||
const adapterDir = path.resolve(srcDir, '..', '..', 'mosaic', 'src', 'commands');
|
||||
for (const file of ['prdy.ts', 'mission.ts']) {
|
||||
const text = await readFile(path.join(adapterDir, file), 'utf8');
|
||||
expect(text.includes("'.md'") || text.includes('.md`'), `${file} references a .md path`).toBe(
|
||||
false,
|
||||
);
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,379 @@
|
||||
import { promises as fs } from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import yaml from 'js-yaml';
|
||||
|
||||
import { createPrd, listPrds, parsePrdDocument, prdDirectory, savePrd } from './prd.js';
|
||||
import type {
|
||||
PrdCreateInput,
|
||||
PrdDocument,
|
||||
PrdExportInput,
|
||||
PrdExportResult,
|
||||
PrdImportInput,
|
||||
PrdImportResult,
|
||||
PrdLinkMissionInput,
|
||||
PrdMissionLinkage,
|
||||
PrdPlanForMissionInput,
|
||||
PrdServiceOptions,
|
||||
PrdUpdateInput,
|
||||
} from './types.js';
|
||||
|
||||
/**
|
||||
* PrdService is the SINGLE authority surface for PRD documents.
|
||||
*
|
||||
* Every mutation path (CLI wizard, `mosaic mission --plan`, import) routes
|
||||
* through this service; the YAML store under `docs/prdy/` is the authority and
|
||||
* exported Markdown is a generated view that no code path reads back.
|
||||
*/
|
||||
|
||||
// ── Typed errors ───────────────────────────────────────────────────────────────
|
||||
|
||||
export class PrdError extends Error {
|
||||
constructor(
|
||||
message: string,
|
||||
readonly code: string,
|
||||
) {
|
||||
super(message);
|
||||
this.name = 'PrdError';
|
||||
}
|
||||
}
|
||||
|
||||
export class PrdNotFoundError extends PrdError {
|
||||
constructor(message: string) {
|
||||
super(message, 'PRD_NOT_FOUND');
|
||||
this.name = 'PrdNotFoundError';
|
||||
}
|
||||
}
|
||||
|
||||
export class PrdUpdateError extends PrdError {
|
||||
constructor(message: string) {
|
||||
super(message, 'PRD_UPDATE_INVALID');
|
||||
this.name = 'PrdUpdateError';
|
||||
}
|
||||
}
|
||||
|
||||
/** Structural refusal: the import payload failed schema validation. Nothing is written. */
|
||||
export class PrdImportInvalidError extends PrdError {
|
||||
constructor(
|
||||
message: string,
|
||||
readonly issues?: string,
|
||||
) {
|
||||
super(message, 'PRD_IMPORT_INVALID');
|
||||
this.name = 'PrdImportInvalidError';
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Conflict refusal: an existing PRD shares the imported id but the content
|
||||
* diverges. Carries a PROPOSED successor (existing version + 1) that is only
|
||||
* persisted via an explicit {@link PrdService.acceptSuccessor} call — import
|
||||
* never overwrites and never merges.
|
||||
*/
|
||||
export class PrdImportConflictError extends PrdError {
|
||||
constructor(
|
||||
message: string,
|
||||
readonly existing: PrdDocument,
|
||||
readonly proposal: PrdDocument,
|
||||
) {
|
||||
super(message, 'PRD_IMPORT_CONFLICT');
|
||||
this.name = 'PrdImportConflictError';
|
||||
}
|
||||
}
|
||||
|
||||
// ── Service ────────────────────────────────────────────────────────────────────
|
||||
|
||||
/** The generated-view label carried by every Markdown export. */
|
||||
export const PRD_GENERATED_VIEW_LABEL = 'generated view — do not edit';
|
||||
|
||||
export class PrdService {
|
||||
private readonly projectPath: string;
|
||||
|
||||
constructor(options: PrdServiceOptions) {
|
||||
this.projectPath = options.projectPath;
|
||||
}
|
||||
|
||||
/** Create a new PRD (version 1, draft) in the authority store. */
|
||||
async create(input: PrdCreateInput): Promise<PrdDocument> {
|
||||
return createPrd({
|
||||
name: input.name,
|
||||
projectPath: this.projectPath,
|
||||
template: input.template,
|
||||
interactive: false,
|
||||
});
|
||||
}
|
||||
|
||||
/** Read a PRD by id, or the most recently updated one. */
|
||||
async get(id?: string): Promise<PrdDocument> {
|
||||
const documents = await listPrds(this.projectPath);
|
||||
|
||||
if (id === undefined) {
|
||||
const latest = documents[0];
|
||||
if (latest === undefined) {
|
||||
throw new PrdNotFoundError(`No PRD documents found under docs/prdy/ for this project`);
|
||||
}
|
||||
return latest;
|
||||
}
|
||||
|
||||
const match = documents.find((doc) => doc.id === id);
|
||||
if (match === undefined) {
|
||||
throw new PrdNotFoundError(`PRD id not found: ${id}`);
|
||||
}
|
||||
return match;
|
||||
}
|
||||
|
||||
/** List all PRDs in the authority store (most recently updated first). */
|
||||
async list(): Promise<PrdDocument[]> {
|
||||
return listPrds(this.projectPath);
|
||||
}
|
||||
|
||||
/**
|
||||
* Apply section field patches and bump the content version.
|
||||
* Linkage entries are preserved; linkage writes do NOT bump the version.
|
||||
*/
|
||||
async update(input: PrdUpdateInput): Promise<PrdDocument> {
|
||||
const doc = await this.get(input.id);
|
||||
|
||||
for (const patch of input.sections) {
|
||||
const section = doc.sections.find((candidate) => candidate.id === patch.id);
|
||||
if (section === undefined) {
|
||||
throw new PrdUpdateError(`Unknown section id: ${patch.id}`);
|
||||
}
|
||||
for (const [field, value] of Object.entries(patch.fields)) {
|
||||
if (!(field in section.fields)) {
|
||||
throw new PrdUpdateError(`Unknown field "${field}" on section "${patch.id}"`);
|
||||
}
|
||||
section.fields[field] = value;
|
||||
}
|
||||
}
|
||||
|
||||
doc.version += 1;
|
||||
doc.updatedAt = new Date().toISOString();
|
||||
await savePrd(doc);
|
||||
return doc;
|
||||
}
|
||||
|
||||
/**
|
||||
* Record (or refresh) a mission ↔ PRD linkage on the PRD document.
|
||||
* Persisted in the YAML authority, so it survives restarts.
|
||||
*/
|
||||
async linkMission(input: PrdLinkMissionInput): Promise<PrdDocument> {
|
||||
const doc = await this.get(input.prdId);
|
||||
return this.applyLinkage(doc, input);
|
||||
}
|
||||
|
||||
/** Read back the mission linkages recorded on a PRD. */
|
||||
async listMissionLinks(prdId?: string): Promise<PrdMissionLinkage[]> {
|
||||
const doc = await this.get(prdId);
|
||||
return doc.missions;
|
||||
}
|
||||
|
||||
/**
|
||||
* Mission planning path: create a PRD for a mission AND persist the
|
||||
* mission↔PRD linkage in a single authority write.
|
||||
*/
|
||||
async planForMission(input: PrdPlanForMissionInput): Promise<PrdDocument> {
|
||||
const doc = await this.create({ name: input.name, template: input.template });
|
||||
return this.applyLinkage(doc, {
|
||||
prdId: doc.id,
|
||||
missionId: input.missionId,
|
||||
missionVersion: input.missionVersion,
|
||||
requirementIds: input.requirementIds,
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Render the PRD to a Markdown GENERATED VIEW.
|
||||
*
|
||||
* The output carries source identity (PRD id + version + generated-view
|
||||
* label). It is written under `docs/prdy/<id>.md` and is NEVER read back:
|
||||
* the authority store only loads `.yaml`/`.yml` files, and no code path in
|
||||
* this package parses the exported Markdown.
|
||||
*/
|
||||
async exportMarkdown(input?: PrdExportInput): Promise<PrdExportResult> {
|
||||
const doc = await this.get(input?.id);
|
||||
const content = renderMarkdown(doc);
|
||||
const filePath = input?.outPath ?? path.join(prdDirectory(doc.projectPath), `${doc.id}.md`);
|
||||
|
||||
await fs.mkdir(path.dirname(filePath), { recursive: true });
|
||||
await fs.writeFile(filePath, content, 'utf8');
|
||||
return { filePath, content };
|
||||
}
|
||||
|
||||
/**
|
||||
* Import a YAML PRD document.
|
||||
*
|
||||
* Structural validation (zod) happens BEFORE anything is proposed or
|
||||
* written. A structurally-valid import is persisted as `draft` — validity is
|
||||
* NOT approval. If an existing PRD shares the id with divergent content, a
|
||||
* typed {@link PrdImportConflictError} is thrown carrying a proposed
|
||||
* successor; the original authority document is left byte-identical on disk.
|
||||
*/
|
||||
async importDocument(input: PrdImportInput): Promise<PrdImportResult> {
|
||||
const incoming = await this.readImportFile(input.filePath);
|
||||
|
||||
const existing = (await listPrds(this.projectPath)).find((doc) => doc.id === incoming.id);
|
||||
if (existing === undefined) {
|
||||
const document = this.buildImportedDocument(incoming);
|
||||
await savePrd(document);
|
||||
return { kind: 'created', document };
|
||||
}
|
||||
|
||||
if (canonicalCore(existing) === canonicalCore(incoming)) {
|
||||
return { kind: 'identical', document: existing };
|
||||
}
|
||||
|
||||
throw new PrdImportConflictError(
|
||||
`PRD id "${incoming.id}" already exists with divergent content — refusing to overwrite. ` +
|
||||
`Proposed successor: version ${existing.version + 1} (draft). ` +
|
||||
`Accept explicitly with acceptSuccessor().`,
|
||||
existing,
|
||||
this.buildSuccessor(existing, incoming),
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Explicitly accept a conflicted import as a successor version of the
|
||||
* existing PRD. Re-validates the source file before writing; the successor
|
||||
* is persisted with status `draft` (acceptance of the import is not approval
|
||||
* of the PRD) and the existing mission linkages are carried forward.
|
||||
*/
|
||||
async acceptSuccessor(input: PrdImportInput): Promise<PrdDocument> {
|
||||
const incoming = await this.readImportFile(input.filePath);
|
||||
|
||||
const existing = (await listPrds(this.projectPath)).find((doc) => doc.id === incoming.id);
|
||||
if (existing === undefined) {
|
||||
throw new PrdNotFoundError(
|
||||
`No existing PRD with id "${incoming.id}" — use importDocument to create it`,
|
||||
);
|
||||
}
|
||||
|
||||
const successor = this.buildSuccessor(existing, incoming);
|
||||
await savePrd(successor);
|
||||
return successor;
|
||||
}
|
||||
|
||||
// ── internals ──────────────────────────────────────────────────────────────
|
||||
|
||||
private async applyLinkage(doc: PrdDocument, input: PrdLinkMissionInput): Promise<PrdDocument> {
|
||||
const entry: PrdMissionLinkage = {
|
||||
missionId: input.missionId,
|
||||
missionVersion: input.missionVersion,
|
||||
prdVersion: doc.version,
|
||||
requirementIds: input.requirementIds ?? [],
|
||||
linkedAt: new Date().toISOString(),
|
||||
};
|
||||
|
||||
// One entry per mission: refresh in place if the mission is already linked.
|
||||
const index = doc.missions.findIndex((m) => m.missionId === entry.missionId);
|
||||
if (index === -1) {
|
||||
doc.missions.push(entry);
|
||||
} else {
|
||||
doc.missions[index] = entry;
|
||||
}
|
||||
|
||||
// Linkage is mission-side metadata, not a content revision: bump the
|
||||
// timestamp only so ids/versions stay stable for consumers.
|
||||
doc.updatedAt = new Date().toISOString();
|
||||
await savePrd(doc);
|
||||
return doc;
|
||||
}
|
||||
|
||||
private async readImportFile(filePath: string): Promise<PrdDocument> {
|
||||
let raw: string;
|
||||
try {
|
||||
raw = await fs.readFile(filePath, 'utf8');
|
||||
} catch (error) {
|
||||
throw new PrdImportInvalidError(`Cannot read import file ${filePath}: ${String(error)}`);
|
||||
}
|
||||
|
||||
let parsed: unknown;
|
||||
try {
|
||||
parsed = yaml.load(raw);
|
||||
} catch (error) {
|
||||
throw new PrdImportInvalidError(`Import file is not valid YAML: ${String(error)}`);
|
||||
}
|
||||
|
||||
try {
|
||||
return parsePrdDocument(parsed);
|
||||
} catch (error) {
|
||||
throw new PrdImportInvalidError(
|
||||
`Import file failed PRD schema validation: ${filePath}`,
|
||||
error instanceof Error ? error.message : String(error),
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
private buildImportedDocument(incoming: PrdDocument): PrdDocument {
|
||||
const now = new Date().toISOString();
|
||||
return {
|
||||
...incoming,
|
||||
// The import lands in THIS project's authority store.
|
||||
projectPath: this.projectPath,
|
||||
// A structurally-valid import is not thereby approved.
|
||||
status: 'draft',
|
||||
version: 1,
|
||||
missions: [],
|
||||
createdAt: now,
|
||||
updatedAt: now,
|
||||
};
|
||||
}
|
||||
|
||||
private buildSuccessor(existing: PrdDocument, incoming: PrdDocument): PrdDocument {
|
||||
return {
|
||||
...incoming,
|
||||
id: existing.id,
|
||||
projectPath: existing.projectPath,
|
||||
status: 'draft',
|
||||
version: existing.version + 1,
|
||||
missions: existing.missions,
|
||||
createdAt: existing.createdAt,
|
||||
updatedAt: new Date().toISOString(),
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
// ── Markdown rendering (generated view) ───────────────────────────────────────
|
||||
|
||||
function canonicalCore(doc: PrdDocument): string {
|
||||
return JSON.stringify([doc.title, doc.template, doc.sections]);
|
||||
}
|
||||
|
||||
function renderMarkdown(doc: PrdDocument): string {
|
||||
const lines: string[] = [
|
||||
'<!--',
|
||||
`${PRD_GENERATED_VIEW_LABEL}`,
|
||||
`source-of-truth: docs/prdy/${doc.id}.yaml (YAML authority)`,
|
||||
`prd-id: ${doc.id}`,
|
||||
`prd-version: ${doc.version}`,
|
||||
`generated-at: ${new Date().toISOString()}`,
|
||||
'-->',
|
||||
'',
|
||||
`# ${doc.title}`,
|
||||
'',
|
||||
`**Status:** ${doc.status} · **Version:** ${doc.version} · **Template:** ${doc.template}`,
|
||||
'',
|
||||
];
|
||||
|
||||
if (doc.missions.length > 0) {
|
||||
lines.push('## Mission Linkage', '');
|
||||
for (const mission of doc.missions) {
|
||||
const requirements =
|
||||
mission.requirementIds.length > 0 ? mission.requirementIds.join(', ') : 'none selected';
|
||||
lines.push(
|
||||
`- mission \`${mission.missionId}\` @ version \`${mission.missionVersion}\`` +
|
||||
` (linked at PRD v${mission.prdVersion}) — requirements: ${requirements}`,
|
||||
);
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
for (const section of doc.sections) {
|
||||
lines.push(`## ${section.title}`, '');
|
||||
for (const [field, value] of Object.entries(section.fields)) {
|
||||
lines.push(`### ${field}`, '', value.trim().length > 0 ? value : '_Not set_.', '');
|
||||
}
|
||||
}
|
||||
|
||||
lines.push('---', '', `_End of generated view for ${doc.id} v${doc.version}._`, '');
|
||||
return lines.join('\n');
|
||||
}
|
||||
@@ -0,0 +1,93 @@
|
||||
import type { PrdTemplate } from './types.js';
|
||||
|
||||
export const BUILTIN_PRD_TEMPLATES: Record<string, PrdTemplate> = {
|
||||
software: {
|
||||
id: 'software',
|
||||
name: 'Software Project',
|
||||
fields: ['owner', 'status', 'scopeVersion', 'successMetrics'],
|
||||
sections: [
|
||||
{ id: 'introduction', title: 'Introduction', fields: ['context', 'objective'] },
|
||||
{ id: 'problem-statement', title: 'Problem Statement', fields: ['painPoints'] },
|
||||
{ id: 'scope-non-goals', title: 'Scope / Non-Goals', fields: ['inScope', 'outOfScope'] },
|
||||
{ id: 'user-stories', title: 'User Stories / Requirements', fields: ['stories'] },
|
||||
{ id: 'functional-requirements', title: 'Functional Requirements', fields: ['requirements'] },
|
||||
{
|
||||
id: 'non-functional-requirements',
|
||||
title: 'Non-Functional Requirements',
|
||||
fields: ['performance', 'reliability', 'security'],
|
||||
},
|
||||
{ id: 'acceptance-criteria', title: 'Acceptance Criteria', fields: ['criteria'] },
|
||||
{
|
||||
id: 'technical-considerations',
|
||||
title: 'Technical Considerations',
|
||||
fields: ['constraints', 'dependencies'],
|
||||
},
|
||||
{
|
||||
id: 'risks-open-questions',
|
||||
title: 'Risks / Open Questions',
|
||||
fields: ['risks', 'openQuestions'],
|
||||
},
|
||||
{
|
||||
id: 'milestones-delivery',
|
||||
title: 'Milestones / Delivery',
|
||||
fields: ['milestones', 'timeline'],
|
||||
},
|
||||
],
|
||||
},
|
||||
feature: {
|
||||
id: 'feature',
|
||||
name: 'Feature PRD',
|
||||
fields: ['owner', 'status', 'releaseTarget'],
|
||||
sections: [
|
||||
{ id: 'problem-statement', title: 'Problem Statement', fields: ['problem'] },
|
||||
{ id: 'goals', title: 'Goals', fields: ['goals'] },
|
||||
{ id: 'scope', title: 'Scope', fields: ['inScope', 'outOfScope'] },
|
||||
{ id: 'user-stories', title: 'User Stories', fields: ['stories'] },
|
||||
{ id: 'requirements', title: 'Requirements', fields: ['functional', 'nonFunctional'] },
|
||||
{ id: 'acceptance-criteria', title: 'Acceptance Criteria', fields: ['criteria'] },
|
||||
{
|
||||
id: 'technical-considerations',
|
||||
title: 'Technical Considerations',
|
||||
fields: ['constraints'],
|
||||
},
|
||||
{
|
||||
id: 'risks-open-questions',
|
||||
title: 'Risks / Open Questions',
|
||||
fields: ['risks', 'questions'],
|
||||
},
|
||||
{ id: 'milestones', title: 'Milestones', fields: ['milestones'] },
|
||||
{ id: 'success-metrics', title: 'Success Metrics / Testing', fields: ['metrics', 'testing'] },
|
||||
],
|
||||
},
|
||||
spike: {
|
||||
id: 'spike',
|
||||
name: 'Research Spike',
|
||||
fields: ['owner', 'status', 'decisionDeadline'],
|
||||
sections: [
|
||||
{ id: 'background', title: 'Background', fields: ['context'] },
|
||||
{ id: 'research-questions', title: 'Research Questions', fields: ['questions'] },
|
||||
{ id: 'constraints', title: 'Constraints', fields: ['constraints'] },
|
||||
{ id: 'options', title: 'Options Considered', fields: ['options'] },
|
||||
{ id: 'evaluation', title: 'Evaluation Criteria', fields: ['criteria'] },
|
||||
{ id: 'findings', title: 'Findings', fields: ['findings'] },
|
||||
{ id: 'recommendation', title: 'Recommendation', fields: ['recommendation'] },
|
||||
{ id: 'risks', title: 'Risks / Unknowns', fields: ['risks', 'unknowns'] },
|
||||
{ id: 'next-steps', title: 'Next Steps', fields: ['nextSteps'] },
|
||||
{ id: 'milestones', title: 'Milestones / Delivery', fields: ['milestones'] },
|
||||
],
|
||||
},
|
||||
};
|
||||
|
||||
export function resolveTemplate(templateName?: string): PrdTemplate {
|
||||
const name =
|
||||
templateName === undefined || templateName.trim().length === 0 ? 'software' : templateName;
|
||||
|
||||
const template = BUILTIN_PRD_TEMPLATES[name];
|
||||
if (template === undefined) {
|
||||
throw new Error(
|
||||
`Unknown PRD template: ${name}. Expected one of: ${Object.keys(BUILTIN_PRD_TEMPLATES).join(', ')}`,
|
||||
);
|
||||
}
|
||||
|
||||
return template;
|
||||
}
|
||||
@@ -0,0 +1,113 @@
|
||||
export type PrdStatus = 'draft' | 'review' | 'approved' | 'archived';
|
||||
|
||||
export interface PrdTemplateSection {
|
||||
id: string;
|
||||
title: string;
|
||||
fields: string[];
|
||||
}
|
||||
|
||||
export interface PrdTemplate {
|
||||
id: string;
|
||||
name: string;
|
||||
sections: PrdTemplateSection[];
|
||||
fields: string[];
|
||||
}
|
||||
|
||||
export interface PrdSection {
|
||||
id: string;
|
||||
title: string;
|
||||
fields: Record<string, string>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Mission ↔ PRD linkage recorded on the PRD document (the YAML authority).
|
||||
*
|
||||
* `missionVersion` is the mission-side revision marker available to the CLI
|
||||
* (the gateway exposes `updatedAt` for missions — there is no numeric mission
|
||||
* version yet). `prdVersion` snapshots the PRD content version at link time.
|
||||
*/
|
||||
export interface PrdMissionLinkage {
|
||||
missionId: string;
|
||||
missionVersion: string;
|
||||
prdVersion: number;
|
||||
requirementIds: string[];
|
||||
linkedAt: string;
|
||||
}
|
||||
|
||||
export interface PrdDocument {
|
||||
id: string;
|
||||
title: string;
|
||||
status: PrdStatus;
|
||||
projectPath: string;
|
||||
template: string;
|
||||
/** Content revision counter. Bumped by updates and accepted imports. */
|
||||
version: number;
|
||||
sections: PrdSection[];
|
||||
missions: PrdMissionLinkage[];
|
||||
createdAt: string;
|
||||
updatedAt: string;
|
||||
}
|
||||
|
||||
export interface CreatePrdOptions {
|
||||
name: string;
|
||||
projectPath: string;
|
||||
template?: string;
|
||||
interactive?: boolean;
|
||||
}
|
||||
|
||||
// ── PrdService surface (single authority entry point) ─────────────────────────
|
||||
|
||||
export interface PrdServiceOptions {
|
||||
projectPath: string;
|
||||
}
|
||||
|
||||
export interface PrdCreateInput {
|
||||
name: string;
|
||||
template?: string;
|
||||
}
|
||||
|
||||
export interface PrdSectionPatch {
|
||||
id: string;
|
||||
fields: Record<string, string>;
|
||||
}
|
||||
|
||||
export interface PrdUpdateInput {
|
||||
/** Defaults to the most recently updated PRD. */
|
||||
id?: string;
|
||||
sections: PrdSectionPatch[];
|
||||
}
|
||||
|
||||
export interface PrdLinkMissionInput {
|
||||
/** Defaults to the most recently updated PRD. */
|
||||
prdId?: string;
|
||||
missionId: string;
|
||||
missionVersion: string;
|
||||
requirementIds?: string[];
|
||||
}
|
||||
|
||||
export interface PrdPlanForMissionInput extends PrdLinkMissionInput {
|
||||
name: string;
|
||||
template?: string;
|
||||
}
|
||||
|
||||
export interface PrdExportInput {
|
||||
/** Defaults to the most recently updated PRD. */
|
||||
id?: string;
|
||||
/** Override the generated-view output path. */
|
||||
outPath?: string;
|
||||
}
|
||||
|
||||
export interface PrdExportResult {
|
||||
filePath: string;
|
||||
content: string;
|
||||
}
|
||||
|
||||
/** Discriminated result of a non-conflicting import. */
|
||||
export type PrdImportResult =
|
||||
| { kind: 'created'; document: PrdDocument }
|
||||
| { kind: 'identical'; document: PrdDocument };
|
||||
|
||||
export interface PrdImportInput {
|
||||
/** Path to a YAML-serialized PRD document (NOT the generated Markdown view). */
|
||||
filePath: string;
|
||||
}
|
||||
@@ -0,0 +1,114 @@
|
||||
import path from 'node:path';
|
||||
|
||||
import { cancel, intro, isCancel, outro, select, text } from '@clack/prompts';
|
||||
|
||||
import { PrdService } from './service.js';
|
||||
import type { CreatePrdOptions, PrdDocument, PrdSectionPatch } from './types.js';
|
||||
|
||||
interface WizardAnswers {
|
||||
goals: string;
|
||||
constraints: string;
|
||||
milestones: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Translate wizard answers into section patches using the same keyword
|
||||
* matching the wizard always used (first section whose id contains the
|
||||
* keyword, then first field whose name contains it, else first field).
|
||||
*/
|
||||
function buildWizardPatches(doc: PrdDocument, answers: WizardAnswers): PrdSectionPatch[] {
|
||||
const bySection = new Map<string, PrdSectionPatch>();
|
||||
|
||||
const add = (keyword: string, value: string): void => {
|
||||
const section = doc.sections.find((candidate) => candidate.id.includes(keyword));
|
||||
if (section === undefined) {
|
||||
return;
|
||||
}
|
||||
|
||||
const fieldName =
|
||||
Object.keys(section.fields).find((field) => field.toLowerCase().includes(keyword)) ??
|
||||
Object.keys(section.fields)[0];
|
||||
|
||||
if (fieldName === undefined || section.fields[fieldName] === value) {
|
||||
return;
|
||||
}
|
||||
|
||||
const existing = bySection.get(section.id);
|
||||
if (existing === undefined) {
|
||||
bySection.set(section.id, { id: section.id, fields: { [fieldName]: value } });
|
||||
} else {
|
||||
existing.fields[fieldName] = value;
|
||||
}
|
||||
};
|
||||
|
||||
add('goal', answers.goals);
|
||||
add('constraint', answers.constraints);
|
||||
add('milestone', answers.milestones);
|
||||
|
||||
return [...bySection.values()];
|
||||
}
|
||||
|
||||
async function promptText(message: string, initialValue = ''): Promise<string> {
|
||||
const response = await text({
|
||||
message,
|
||||
initialValue,
|
||||
});
|
||||
|
||||
if (isCancel(response)) {
|
||||
cancel('PRD wizard cancelled.');
|
||||
throw new Error('PRD wizard cancelled');
|
||||
}
|
||||
|
||||
return response.trim();
|
||||
}
|
||||
|
||||
async function promptTemplate(template?: string): Promise<string> {
|
||||
if (template !== undefined && template.trim().length > 0) {
|
||||
return template;
|
||||
}
|
||||
|
||||
const choice = await select({
|
||||
message: 'PRD type',
|
||||
options: [
|
||||
{ value: 'software', label: 'Software project' },
|
||||
{ value: 'feature', label: 'Feature' },
|
||||
{ value: 'spike', label: 'Research spike' },
|
||||
],
|
||||
});
|
||||
|
||||
if (isCancel(choice)) {
|
||||
cancel('PRD wizard cancelled.');
|
||||
throw new Error('PRD wizard cancelled');
|
||||
}
|
||||
|
||||
return choice;
|
||||
}
|
||||
|
||||
/**
|
||||
* Interactive PRD wizard. All writes go through PrdService — the wizard is a
|
||||
* prompt layer, never a second writer path.
|
||||
*/
|
||||
export async function runPrdWizard(options: CreatePrdOptions): Promise<PrdDocument> {
|
||||
intro('Mosaic PRD wizard');
|
||||
|
||||
const name =
|
||||
options.name.trim().length > 0 ? options.name.trim() : await promptText('Project name');
|
||||
const template = await promptTemplate(options.template);
|
||||
const goals = await promptText('Primary goals');
|
||||
const constraints = await promptText('Key constraints');
|
||||
const milestones = await promptText('Planned milestones');
|
||||
|
||||
const service = new PrdService({ projectPath: options.projectPath });
|
||||
const doc = await service.create({
|
||||
name,
|
||||
template,
|
||||
});
|
||||
|
||||
const patches = buildWizardPatches(doc, { goals, constraints, milestones });
|
||||
const updated =
|
||||
patches.length > 0 ? await service.update({ id: doc.id, sections: patches }) : doc;
|
||||
|
||||
outro(`PRD created: ${path.join(updated.projectPath, 'docs', 'prdy', `${updated.id}.yaml`)}`);
|
||||
|
||||
return updated;
|
||||
}
|
||||
Reference in New Issue
Block a user