@s_s/harmonia 1.0.0 → 1.1.0

package/build/core/registry.js

@@ -22,13 +22,14 @@
  */
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { homedir } from 'node:os';
-import { platform } from 'node:os';
+import { createKit } from '@s_s/agent-kit';
 const REGISTRY_FILE = 'registry.json';
+/** Shared kit instance for data directory resolution */
+const kit = createKit('harmonia');
 /**
  * Get the global Harmonia data directory, following system conventions.
  *
- * Resolution order:
+ * Delegates to @s_s/agent-kit which handles:
  *   1. HARMONIA_DATA_DIR env var (explicit override)
  *   2. Platform default:
  *      - macOS:   ~/Library/Application Support/harmonia
@@ -36,19 +37,7 @@ const REGISTRY_FILE = 'registry.json';
  *      - Linux:   $XDG_DATA_HOME/harmonia (defaults to ~/.local/share/harmonia)
  */
 export function getGlobalDir() {
-    const envDir = process.env.HARMONIA_DATA_DIR;
-    if (envDir)
-        return envDir;
-    const home = homedir();
-    switch (platform()) {
-        case 'darwin':
-            return join(home, 'Library', 'Application Support', 'harmonia');
-        case 'win32':
-            return join(process.env.APPDATA || join(home, 'AppData', 'Roaming'), 'harmonia');
-        default:
-            // Linux and others: follow XDG Base Directory spec
-            return join(process.env.XDG_DATA_HOME || join(home, '.local', 'share'), 'harmonia');
-    }
+    return kit.getDataDir();
 }
 /**
  * Get the data directory for a specific project within the global dir.

package/build/core/registry.js.map

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

package/build/core/schema.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Document schema loader and validator.
+ *
+ * Loads schema definitions from the resolved workflow directory's schemas/ subdirectory
+ * and validates document content against them before writing.
+ */
+import type { DocSchema, ProjectScale } from './types.js';
+/**
+ * Load a document schema from the workflow's schemas directory.
+ * Returns undefined if no schema file exists for this doc_id.
+ *
+ * For step schemas, pass a composite id like "prd.requirements".
+ */
+export declare function loadDocSchema(builtinDir: string, customDir: string, workflowName: string, docId: string): Promise<DocSchema | undefined>;
+export interface ValidationError {
+    /** Error type */
+    type: 'missing_section' | 'missing_html_tag' | 'content_too_short' | 'empty_content' | 'missing_json_field' | 'invalid_json' | 'wrong_json_type' | 'json_array_too_short';
+    /** Human-readable message */
+    message: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+/**
+ * Validate document content against a schema.
+ *
+ * @param content  - Document content (markdown, HTML, or JSON)
+ * @param schema   - Schema definition
+ * @param scale    - Project scale (affects which sections are required). When null, scale-dependent checks are skipped.
+ * @param isHtml   - Whether the document is HTML format
+ * @param isJson   - Whether the document is JSON format (for step artifacts)
+ */
+export declare function validateDoc(content: string, schema: DocSchema, scale: ProjectScale | null, isHtml?: boolean, isJson?: boolean): ValidationResult;
+/**
+ * Format validation errors into a human-readable string for tool response.
+ */
+export declare function formatValidationErrors(errors: ValidationError[]): string;

package/build/core/schema.js

@@ -0,0 +1,187 @@
+/**
+ * Document schema loader and validator.
+ *
+ * Loads schema definitions from the resolved workflow directory's schemas/ subdirectory
+ * and validates document content against them before writing.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { resolveWorkflowDir } from './workflow.js';
+// ─── Schema Loading ───
+/**
+ * Load a document schema from the workflow's schemas directory.
+ * Returns undefined if no schema file exists for this doc_id.
+ *
+ * For step schemas, pass a composite id like "prd.requirements".
+ */
+export async function loadDocSchema(builtinDir, customDir, workflowName, docId) {
+    const workflowDir = await resolveWorkflowDir(builtinDir, customDir, workflowName);
+    const schemaPath = join(workflowDir, 'schemas', `${docId}.json`);
+    try {
+        const raw = await readFile(schemaPath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Normalize a heading string for comparison.
+ * Strips leading #'s and whitespace, lowercases.
+ */
+function normalizeHeading(heading) {
+    return heading
+        .replace(/^#+\s*/, '')
+        .trim()
+        .toLowerCase();
+}
+/**
+ * Extract the heading level (number of #) from a heading string.
+ */
+function headingLevel(heading) {
+    const match = heading.match(/^(#+)/);
+    return match ? match[1].length : 0;
+}
+/**
+ * Extract all headings from markdown content.
+ * Returns array of raw heading lines (e.g. "## 项目概述").
+ */
+function extractHeadings(content) {
+    const lines = content.split('\n');
+    return lines.filter((line) => /^#{1,6}\s+/.test(line.trim()));
+}
+/**
+ * Check if a required section is present in the document headings.
+ * Matches primary heading or any alias, with level-aware + normalized comparison.
+ */
+function sectionPresent(section, headings) {
+    const candidates = [section.heading, ...(section.aliases ?? [])];
+    const level = headingLevel(section.heading);
+    for (const candidate of candidates) {
+        const candidateNorm = normalizeHeading(candidate);
+        const candidateLevel = headingLevel(candidate) || level;
+        for (const h of headings) {
+            if (headingLevel(h) === candidateLevel && normalizeHeading(h) === candidateNorm) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Validate document content against a schema.
+ *
+ * @param content  - Document content (markdown, HTML, or JSON)
+ * @param schema   - Schema definition
+ * @param scale    - Project scale (affects which sections are required). When null, scale-dependent checks are skipped.
+ * @param isHtml   - Whether the document is HTML format
+ * @param isJson   - Whether the document is JSON format (for step artifacts)
+ */
+export function validateDoc(content, schema, scale, isHtml = false, isJson = false) {
+    const errors = [];
+    // Empty content check
+    const trimmed = content.trim();
+    if (!trimmed) {
+        return {
+            valid: false,
+            errors: [{ type: 'empty_content', message: '文档内容为空' }],
+        };
+    }
+    // Minimum length check
+    if (schema.minLength && trimmed.length < schema.minLength) {
+        errors.push({
+            type: 'content_too_short',
+            message: `文档内容过短（${trimmed.length} 字符），最少需要 ${schema.minLength} 字符`,
+        });
+    }
+    // Markdown section checks
+    if (schema.sections && !isHtml && !isJson) {
+        const headings = extractHeadings(content);
+        for (const section of schema.sections) {
+            // When scale is null, skip scale-dependent section requirements
+            const isRequired = scale !== null ? section.required[scale] : false;
+            if (isRequired && !sectionPresent(section, headings)) {
+                const aliasList = section.aliases?.length ? `（或: ${section.aliases.join(', ')}）` : '';
+                errors.push({
+                    type: 'missing_section',
+                    message: `缺少必需章节: ${section.heading}${aliasList}`,
+                });
+            }
+        }
+    }
+    // HTML tag checks
+    if (schema.htmlTags && isHtml) {
+        for (const tag of schema.htmlTags) {
+            // Check for opening tag (case-insensitive)
+            const regex = new RegExp(`<${tag}[\\s>]`, 'i');
+            if (!regex.test(content)) {
+                errors.push({
+                    type: 'missing_html_tag',
+                    message: `缺少必需的 HTML 标签: <${tag}>`,
+                });
+            }
+        }
+    }
+    // JSON field checks
+    if (schema.jsonFields && isJson) {
+        let parsed = null;
+        try {
+            parsed = JSON.parse(content);
+        }
+        catch {
+            errors.push({
+                type: 'invalid_json',
+                message: '内容不是合法的 JSON 格式',
+            });
+        }
+        if (parsed) {
+            for (const fieldDef of schema.jsonFields) {
+                // When scale is null, skip scale-dependent field requirements
+                const isRequired = scale !== null ? fieldDef.required[scale] : false;
+                if (!isRequired)
+                    continue;
+                const value = parsed[fieldDef.field];
+                if (value === undefined || value === null) {
+                    errors.push({
+                        type: 'missing_json_field',
+                        message: `缺少必需的 JSON 字段: "${fieldDef.field}"`,
+                    });
+                    continue;
+                }
+                // Type check
+                if (fieldDef.type) {
+                    const actualType = Array.isArray(value) ? 'array' : typeof value;
+                    if (actualType !== fieldDef.type) {
+                        errors.push({
+                            type: 'wrong_json_type',
+                            message: `字段 "${fieldDef.field}" 类型错误: 期望 ${fieldDef.type}，实际 ${actualType}`,
+                        });
+                        continue;
+                    }
+                }
+                // Array minItems check
+                if (fieldDef.minItems && Array.isArray(value) && value.length < fieldDef.minItems) {
+                    errors.push({
+                        type: 'json_array_too_short',
+                        message: `字段 "${fieldDef.field}" 数组元素过少: 最少 ${fieldDef.minItems} 个，实际 ${value.length} 个`,
+                    });
+                }
+            }
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+/**
+ * Format validation errors into a human-readable string for tool response.
+ */
+export function formatValidationErrors(errors) {
+    const lines = ['文档校验失败，请修正后重新提交：', ''];
+    for (const err of errors) {
+        lines.push(`- ${err.message}`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=schema.js.map

package/build/core/schema.js.map

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

package/build/core/state.d.ts

@@ -2,12 +2,18 @@
  * Project state management — manages <data_dir>/<project_name>/state.json
  */
 import type { PhaseStatus, ProjectScale, ProjectState, LoadedWorkflow } from './types.js';
+/**
+ * Error thrown when a tool requires scale but it hasn't been set yet.
+ */
+export declare class ScaleNotSetError extends Error {
+    constructor(projectName: string);
+}
 /**
  * Initialize a new project state file.
  * Note: directory creation and registry are handled by registry.registerProject().
  * This only writes the state.json.
  */
-export declare function initProjectState(projectName: string, projectDir: string, workflow: LoadedWorkflow, scale?: ProjectScale): Promise<ProjectState>;
+export declare function initProjectState(projectName: string, projectDir: string, workflow: LoadedWorkflow): Promise<ProjectState>;
 /**
  * Read the current project state.
  */
@@ -24,3 +30,7 @@ export declare function updatePhaseStatus(projectName: string, phaseId: string,
  * Check if a project state file exists.
  */
 export declare function projectStateExists(projectName: string): Promise<boolean>;
+/**
+ * Set the project scale. Scale is immutable once set.
+ */
+export declare function setScale(projectName: string, scale: ProjectScale): Promise<ProjectState>;

package/build/core/state.js

@@ -4,6 +4,15 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
 import { getProjectDataDir } from './registry.js';
+/**
+ * Error thrown when a tool requires scale but it hasn't been set yet.
+ */
+export class ScaleNotSetError extends Error {
+    constructor(projectName) {
+        super(`项目 "${projectName}" 尚未设定 scale。请先完成 PRD 审批，然后调用 project_set_scale 设定项目规模。`);
+        this.name = 'ScaleNotSetError';
+    }
+}
 const STATE_FILE = 'state.json';
 function statePath(projectName) {
     return join(getProjectDataDir(projectName), STATE_FILE);
@@ -13,7 +22,7 @@ function statePath(projectName) {
  * Note: directory creation and registry are handled by registry.registerProject().
  * This only writes the state.json.
  */
-export async function initProjectState(projectName, projectDir, workflow, scale = 'small') {
+export async function initProjectState(projectName, projectDir, workflow) {
     const now = new Date().toISOString();
     const phases = workflow.definition.phases;
     const firstPhaseId = phases[0]?.id ?? '';
@@ -21,7 +30,7 @@ export async function initProjectState(projectName, projectDir, workflow, scale
         projectName,
         projectDir,
         workflow: workflow.definition.name,
-        scale,
+        scale: null,
         currentPhase: firstPhaseId,
         phases: phases.map((p, i) => ({
             id: p.id,
@@ -100,4 +109,16 @@ export async function projectStateExists(projectName) {
         return false;
     }
 }
+/**
+ * Set the project scale. Scale is immutable once set.
+ */
+export async function setScale(projectName, scale) {
+    const state = await readState(projectName);
+    if (state.scale !== null) {
+        throw new Error(`Scale 已设定为 "${state.scale}"，不可更改。如需调整规模，请重新评估 PRD。`);
+    }
+    state.scale = scale;
+    await writeState(projectName, state);
+    return state;
+}
 //# sourceMappingURL=state.js.map

package/build/core/state.js.map

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

package/build/core/steps.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Step state management — manages <data_dir>/<project_name>/steps.json
+ *
+ * Tracks which sequential steps have been completed for each document,
+ * supporting the P3 Sequential mode feature.
+ */
+import type { DocStepState } from './types.js';
+/**
+ * Read the steps state for a project.
+ */
+export declare function readSteps(projectName: string): Promise<Record<string, DocStepState>>;
+/**
+ * Get the step state for a specific document.
+ */
+export declare function getDocStepState(projectName: string, docId: string): Promise<DocStepState | null>;
+/**
+ * Get the set of completed step IDs for a document.
+ */
+export declare function getCompletedStepIds(state: DocStepState | null): Set<string>;
+/**
+ * Record a step as completed. If the step was already completed,
+ * it is overwritten and all subsequent steps are cleared (rollback).
+ *
+ * @returns The updated DocStepState
+ */
+export declare function recordStepCompletion(projectName: string, docId: string, stepId: string, artifactPath: string, allStepIds: string[]): Promise<DocStepState>;
+/**
+ * Mark a document as finalized (all steps completed + final doc written).
+ */
+export declare function markFinalized(projectName: string, docId: string): Promise<DocStepState>;
+/**
+ * Check if a document's sequential process is finalized.
+ */
+export declare function isDocFinalized(projectName: string, docId: string): Promise<boolean>;

package/build/core/steps.js

@@ -0,0 +1,113 @@
+/**
+ * Step state management — manages <data_dir>/<project_name>/steps.json
+ *
+ * Tracks which sequential steps have been completed for each document,
+ * supporting the P3 Sequential mode feature.
+ */
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { getProjectDataDir } from './registry.js';
+const STEPS_FILE = 'steps.json';
+function stepsPath(projectName) {
+    return join(getProjectDataDir(projectName), STEPS_FILE);
+}
+/**
+ * Read the steps state for a project.
+ */
+export async function readSteps(projectName) {
+    try {
+        const content = await readFile(stepsPath(projectName), 'utf-8');
+        const data = JSON.parse(content);
+        return data.docs ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Write steps state to disk.
+ */
+async function writeSteps(projectName, docs) {
+    const filePath = stepsPath(projectName);
+    await mkdir(dirname(filePath), { recursive: true });
+    const data = { docs };
+    await writeFile(filePath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Get the step state for a specific document.
+ */
+export async function getDocStepState(projectName, docId) {
+    const docs = await readSteps(projectName);
+    return docs[docId] ?? null;
+}
+/**
+ * Get the set of completed step IDs for a document.
+ */
+export function getCompletedStepIds(state) {
+    if (!state)
+        return new Set();
+    return new Set(state.completedSteps.map((s) => s.stepId));
+}
+/**
+ * Record a step as completed. If the step was already completed,
+ * it is overwritten and all subsequent steps are cleared (rollback).
+ *
+ * @returns The updated DocStepState
+ */
+export async function recordStepCompletion(projectName, docId, stepId, artifactPath, allStepIds) {
+    const docs = await readSteps(projectName);
+    let state = docs[docId];
+    if (!state) {
+        state = {
+            docId,
+            completedSteps: [],
+            finalized: false,
+        };
+    }
+    // Find the index of this step in the workflow's step order
+    const stepIndex = allStepIds.indexOf(stepId);
+    // Check if this step was already completed — if so, rollback subsequent steps
+    const existingIndex = state.completedSteps.findIndex((s) => s.stepId === stepId);
+    if (existingIndex >= 0) {
+        // Clear this step and all subsequent steps
+        state.completedSteps = state.completedSteps.filter((s) => {
+            const sIdx = allStepIds.indexOf(s.stepId);
+            return sIdx < stepIndex;
+        });
+        // Reset finalized flag
+        state.finalized = false;
+        delete state.finalizedAt;
+    }
+    // Record the new step
+    const record = {
+        stepId,
+        completedAt: new Date().toISOString(),
+        artifactPath,
+    };
+    state.completedSteps.push(record);
+    docs[docId] = state;
+    await writeSteps(projectName, docs);
+    return state;
+}
+/**
+ * Mark a document as finalized (all steps completed + final doc written).
+ */
+export async function markFinalized(projectName, docId) {
+    const docs = await readSteps(projectName);
+    const state = docs[docId];
+    if (!state) {
+        throw new Error(`No step state found for document "${docId}"`);
+    }
+    state.finalized = true;
+    state.finalizedAt = new Date().toISOString();
+    await writeSteps(projectName, docs);
+    return state;
+}
+/**
+ * Check if a document's sequential process is finalized.
+ */
+export async function isDocFinalized(projectName, docId) {
+    const state = await getDocStepState(projectName, docId);
+    return state?.finalized ?? false;
+}
+//# sourceMappingURL=steps.js.map

package/build/core/steps.js.map

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