@evref-bl/dev-nexus 0.1.0-alpha.0

package/dist/nexusProjectTemplate.js

@@ -0,0 +1,354 @@
+import fs from "node:fs";
+import path from "node:path";
+import { devNexusProjectConfigFileName, projectWorktreesRootPath, } from "./nexusProjectConfig.js";
+import { resolveProjectComponents } from "./nexusProjectLifecycle.js";
+import { defaultLocalWorkTrackingStorePath } from "./workTrackingLocalProvider.js";
+export function buildNexusProjectTemplateLayout(options) {
+    const projectRoot = path.resolve(options.projectRoot);
+    const components = resolveProjectComponents(projectRoot, options.projectConfig);
+    const automationConfig = options.projectConfig.automation;
+    const entries = [
+        {
+            area: "component_configuration",
+            owner: "user_authored",
+            path: devNexusProjectConfigFileName,
+            sourceControl: "source",
+            description: "Project, component, work-item service, automation, skills, plugins, and agent MCP configuration.",
+        },
+        {
+            area: "project_state",
+            owner: "generated",
+            path: ".dev-nexus/README.md",
+            sourceControl: "support",
+            description: "Generated map of project support state, runtime state, and migration boundaries.",
+        },
+    ];
+    for (const component of components) {
+        entries.push({
+            area: "component_configuration",
+            owner: "user_authored",
+            path: displayPath(projectRoot, component.sourceRoot),
+            sourceControl: "source",
+            description: `Source root for component ${component.id}.`,
+        });
+        entries.push({
+            area: "project_state",
+            owner: "local_runtime",
+            path: displayPath(projectRoot, component.worktreesRoot, true),
+            sourceControl: "local",
+            description: `Generated implementation worktrees for component ${component.id}.`,
+        });
+    }
+    if (automationConfig) {
+        entries.push({
+            area: "target_state",
+            owner: "user_authored",
+            path: normalizedProjectRelativePath(automationConfig.target.statePath),
+            sourceControl: "support",
+            description: "Concise target memory maintained by humans or launched agents as current direction changes.",
+        });
+        entries.push({
+            area: "project_state",
+            owner: "local_runtime",
+            path: normalizedProjectRelativePath(automationConfig.target.cycleLedgerPath),
+            sourceControl: "local",
+            description: "Caller-reported target cycle facts used for reports and relaunch decisions.",
+        });
+        entries.push({
+            area: "project_state",
+            owner: "local_runtime",
+            path: normalizedProjectRelativePath(automationConfig.ledger.path),
+            sourceControl: "local",
+            description: "Automation run ledger written by DevNexus.",
+        });
+        entries.push({
+            area: "project_state",
+            owner: "local_runtime",
+            path: normalizedProjectRelativePath(automationConfig.lock.path),
+            sourceControl: "local",
+            description: "Automation lock file used to prevent overlapping runs.",
+        });
+        entries.push({
+            area: "project_state",
+            owner: "local_runtime",
+            path: ".dev-nexus/automation/agent-launches/",
+            sourceControl: "local",
+            description: "Per-run agent context and result files produced during agent-launch automation.",
+        });
+    }
+    if (options.skillsConfig !== false) {
+        entries.push({
+            area: "skills",
+            owner: "generated",
+            path: ".dev-nexus/skills/",
+            sourceControl: "support",
+            description: "DevNexus-owned curated skill definitions.",
+        });
+        for (const target of resolvedSkillAgentTargets(options.skillsConfig)) {
+            entries.push({
+                area: "skills",
+                owner: "generated",
+                path: withTrailingSlash(normalizedProjectRelativePath(target.directory)),
+                sourceControl: target.sourceControl,
+                description: `Agent-native skill projection for ${target.agent}.`,
+            });
+        }
+    }
+    if (options.mcpConfig && options.mcpConfig.enabled !== false) {
+        for (const target of resolvedMcpAgentTargets(options.mcpConfig)) {
+            entries.push({
+                area: "agent_mcp_projection",
+                owner: "generated",
+                path: normalizedProjectRelativePath(target.configPath),
+                sourceControl: target.sourceControl,
+                description: `Agent MCP server projection for ${target.agent}.`,
+            });
+        }
+    }
+    for (const storePath of localWorkItemStorePaths(projectRoot, options.projectConfig)) {
+        entries.push({
+            area: "project_state",
+            owner: "local_runtime",
+            path: displayPath(projectRoot, storePath),
+            sourceControl: "local",
+            description: "Local work-item store for a configured component tracker.",
+        });
+    }
+    return {
+        entries,
+        migrationNotes: nexusProjectTemplateMigrationNotes(),
+    };
+}
+export function materializeNexusProjectTemplate(options) {
+    const projectRoot = path.resolve(options.projectRoot);
+    const layout = buildNexusProjectTemplateLayout(options);
+    const components = resolveProjectComponents(projectRoot, options.projectConfig);
+    const componentWorktreesRoots = components.map((component) => component.worktreesRoot);
+    fs.mkdirSync(options.worktreesRoot, { recursive: true });
+    for (const componentWorktreesRoot of componentWorktreesRoots) {
+        fs.mkdirSync(componentWorktreesRoot, { recursive: true });
+    }
+    const supportReadmePath = path.join(projectRoot, ".dev-nexus", "README.md");
+    fs.mkdirSync(path.dirname(supportReadmePath), { recursive: true });
+    fs.writeFileSync(supportReadmePath, renderNexusProjectSupportReadme(layout), "utf8");
+    const targetStatePath = options.projectConfig.automation
+        ? path.resolve(projectRoot, options.projectConfig.automation.target.statePath)
+        : null;
+    if (targetStatePath && !fs.existsSync(targetStatePath)) {
+        fs.mkdirSync(path.dirname(targetStatePath), { recursive: true });
+        fs.writeFileSync(targetStatePath, defaultTargetStateMarkdown(), "utf8");
+    }
+    const gitExclude = options.excludeFromGit === false
+        ? { gitExcludePath: null, gitExcludeEntries: [] }
+        : addGitExcludeEntries(projectRoot, templateGitExcludeEntries(projectRoot, options.projectConfig));
+    return {
+        ...layout,
+        supportReadmePath,
+        targetStatePath,
+        componentWorktreesRoots,
+        gitExcludePath: gitExclude.gitExcludePath,
+        gitExcludeEntries: gitExclude.gitExcludeEntries,
+    };
+}
+export function nexusProjectTemplateMigrationNotes() {
+    return [
+        "Historical staging roots are migration-only evidence; production templates must not inherit source-specific paths, tracker ids, agent launch commands, or component names from them.",
+        "Generated state can be refreshed by DevNexus and must stay separate from user-authored project config, component source, and target notes.",
+        "Local runtime state records locks, ledgers, local tracker files, and generated worktrees; keep it out of component source roots unless the project explicitly configures that boundary.",
+    ];
+}
+function resolvedSkillAgentTargets(config) {
+    return (config?.agentTargets ?? [])
+        .filter((target) => target.enabled !== false)
+        .map((target) => ({
+        agent: target.agent,
+        directory: skillAgentTargetDirectory(target),
+        sourceControl: target.sourceControl ?? config?.sourceControl ?? "support",
+    }));
+}
+function skillAgentTargetDirectory(target) {
+    if (target.directory) {
+        return target.directory;
+    }
+    if (target.agent === "codex") {
+        return path.join(".agents", "skills");
+    }
+    if (target.agent === "claude") {
+        return path.join(".claude", "skills");
+    }
+    return path.join(`.${target.agent}`, "skills");
+}
+function resolvedMcpAgentTargets(config) {
+    const targets = config.agentTargets ?? [{ agent: "codex" }];
+    return targets
+        .filter((target) => target.enabled !== false)
+        .map((target) => ({
+        agent: target.agent,
+        configPath: mcpAgentTargetConfigPath(target),
+        sourceControl: target.sourceControl ?? config.sourceControl ?? "support",
+    }));
+}
+function mcpAgentTargetConfigPath(target) {
+    if (target.configPath) {
+        return target.configPath;
+    }
+    if (target.agent === "codex") {
+        return path.join(".codex", "config.toml");
+    }
+    if (target.agent === "claude") {
+        return ".mcp.json";
+    }
+    return path.join(`.${target.agent}`, "mcp.json");
+}
+function localWorkItemStorePaths(projectRoot, config) {
+    const paths = new Set();
+    collectLocalWorkTrackingPath(projectRoot, paths, config.workTracking ?? null);
+    for (const component of resolveProjectComponents(projectRoot, config)) {
+        collectLocalWorkTrackingPath(projectRoot, paths, component.workTracking ?? null);
+    }
+    return [...paths];
+}
+function collectLocalWorkTrackingPath(projectRoot, paths, config) {
+    if (config?.provider !== "local") {
+        return;
+    }
+    paths.add(config.storePath
+        ? path.resolve(projectRoot, config.storePath)
+        : defaultLocalWorkTrackingStorePath(projectRoot));
+}
+function templateGitExcludeEntries(projectRoot, config) {
+    const entries = new Set([".dev-nexus/README.md"]);
+    const worktreesEntry = gitExcludeEntryForPath(projectRoot, projectWorktreesRootPath(projectRoot, config), true);
+    if (worktreesEntry) {
+        entries.add(worktreesEntry);
+    }
+    const automationConfig = config.automation;
+    if (automationConfig) {
+        addRelativeEntry(entries, automationConfig.ledger.path);
+        addRelativeEntry(entries, automationConfig.lock.path);
+        addRelativeEntry(entries, automationConfig.target.cycleLedgerPath);
+        entries.add(".dev-nexus/automation/agent-launches/");
+    }
+    for (const storePath of localWorkItemStorePaths(projectRoot, config)) {
+        const entry = gitExcludeEntryForPath(projectRoot, storePath, false);
+        if (entry) {
+            entries.add(entry);
+        }
+    }
+    return [...entries];
+}
+function addRelativeEntry(entries, entry) {
+    if (isProjectRelativePath(entry)) {
+        entries.add(normalizedProjectRelativePath(entry));
+    }
+}
+function renderNexusProjectSupportReadme(layout) {
+    const lines = [
+        "# DevNexus Project Support",
+        "",
+        "## Project Template Layout",
+        "",
+        "DevNexus keeps generic project support state separate from component source, target memory, curated skills, agent MCP projection, and local runtime records.",
+        "",
+        "## Ownership Classes",
+        "",
+        "- `user_authored`: Maintained by humans or launched agents as durable project intent.",
+        "- `generated`: Written or refreshed by DevNexus from project configuration.",
+        "- `local_runtime`: Machine-local state created while checking, launching, or recording work.",
+        "",
+        "## Paths",
+        "",
+        ...layout.entries.map((entry) => `- \`${entry.path}\` - ${entry.area}, ${entry.owner}, ${entry.sourceControl}: ${entry.description}`),
+        "",
+        "## Migration Notes",
+        "",
+        ...layout.migrationNotes.map((note) => `- ${note}`),
+        "",
+    ];
+    return `${lines.join("\n")}`;
+}
+function defaultTargetStateMarkdown() {
+    return [
+        "# Target State",
+        "",
+        "Current direction:",
+        "- No target state recorded yet.",
+        "",
+        "Decisions:",
+        "- None recorded.",
+        "",
+        "Blockers:",
+        "- None recorded.",
+        "",
+    ].join("\n");
+}
+function addGitExcludeEntries(projectRoot, entries) {
+    const gitInfoDir = path.join(projectRoot, ".git", "info");
+    if (!fs.existsSync(gitInfoDir) || !fs.statSync(gitInfoDir).isDirectory()) {
+        return {
+            gitExcludePath: null,
+            gitExcludeEntries: [],
+        };
+    }
+    const excludePath = path.join(gitInfoDir, "exclude");
+    const existing = fs.existsSync(excludePath)
+        ? fs.readFileSync(excludePath, "utf8")
+        : "";
+    const existingLines = new Set(existing
+        .split(/\r?\n/u)
+        .map((line) => line.trim())
+        .filter(Boolean));
+    const appended = [];
+    for (const entry of entries) {
+        if (!existingLines.has(entry)) {
+            appended.push(entry);
+            existingLines.add(entry);
+        }
+    }
+    if (appended.length > 0) {
+        fs.mkdirSync(gitInfoDir, { recursive: true });
+        const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+        fs.appendFileSync(excludePath, `${prefix}${appended.join("\n")}\n`, "utf8");
+    }
+    return {
+        gitExcludePath: excludePath,
+        gitExcludeEntries: appended,
+    };
+}
+function displayPath(projectRoot, targetPath, directory = false) {
+    const resolved = path.resolve(projectRoot, targetPath);
+    const relative = path.relative(projectRoot, resolved);
+    if (relative === "") {
+        return directory ? "./" : ".";
+    }
+    if (relative && !relative.startsWith("..") && !path.isAbsolute(relative)) {
+        return directory
+            ? withTrailingSlash(normalizedProjectRelativePath(relative))
+            : normalizedProjectRelativePath(relative);
+    }
+    return directory
+        ? withTrailingSlash(path.resolve(targetPath))
+        : path.resolve(targetPath);
+}
+function gitExcludeEntryForPath(projectRoot, targetPath, directory) {
+    const relative = path.relative(projectRoot, path.resolve(targetPath));
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+        return null;
+    }
+    const normalized = normalizedProjectRelativePath(relative);
+    return directory ? withTrailingSlash(normalized) : normalized;
+}
+function normalizedProjectRelativePath(value) {
+    return value.replace(/\\/gu, "/");
+}
+function withTrailingSlash(value) {
+    return value.endsWith("/") ? value : `${value}/`;
+}
+function isProjectRelativePath(value) {
+    return (value.trim().length > 0 &&
+        !path.isAbsolute(value) &&
+        !/^[A-Za-z]:/u.test(value) &&
+        !value
+            .split(/[\\/]/u)
+            .some((part) => part === ".." || part === ""));
+}

package/dist/nexusSkills.d.ts

@@ -0,0 +1,134 @@
+export declare const nexusSkillSupportDirectoryName = ".dev-nexus";
+export declare const nexusSkillsDirectoryName = "skills";
+export declare const nexusSkillManifestFileName = "dev-nexus.skill.json";
+export declare const nexusSkillMarkdownFileName = "SKILL.md";
+export type NexusSkillMaterializationMode = "copy" | "symlink" | "reference";
+export type NexusSkillSourceControl = "support" | "source";
+export type NexusSkillAgentId = string;
+export interface NexusProjectSkillAgentTarget {
+    agent: NexusSkillAgentId;
+    enabled?: boolean;
+    directory?: string;
+    sourceControl?: NexusSkillSourceControl;
+}
+export interface NexusSkillSource {
+    type: "curated" | "git" | "url" | "local";
+    uri?: string;
+    commit?: string;
+    checksum?: string;
+}
+export interface NexusSkillManifest {
+    id: string;
+    name: string;
+    description: string;
+    version: string;
+    license: string;
+    source: NexusSkillSource;
+    supportedAgents: string[];
+    materialization: NexusSkillMaterializationMode;
+    sourceControl: NexusSkillSourceControl;
+}
+export interface NexusSkillDefinition {
+    manifest: NexusSkillManifest;
+    files: Record<string, string>;
+    sourcePath?: string;
+}
+export interface NexusProjectSkillSelection {
+    id: string;
+    enabled?: boolean;
+    version?: string;
+    materialization?: NexusSkillMaterializationMode;
+    sourceControl?: NexusSkillSourceControl;
+}
+export interface NexusProjectSkillsConfig {
+    defaultCorePack?: boolean;
+    materialization?: NexusSkillMaterializationMode;
+    sourceControl?: NexusSkillSourceControl;
+    agentTargets?: NexusProjectSkillAgentTarget[];
+    items?: NexusProjectSkillSelection[];
+}
+export interface MaterializeNexusProjectSkillsOptions {
+    projectRoot: string;
+    skillsConfig?: NexusProjectSkillsConfig;
+    skillDefinitions?: NexusSkillDefinition[];
+    excludeFromGit?: boolean;
+}
+export interface MaterializedNexusSkill {
+    id: string;
+    name: string;
+    version: string;
+    materialization: NexusSkillMaterializationMode;
+    sourceControl: NexusSkillSourceControl;
+    skillRoot: string;
+    manifestPath: string;
+    skillPath: string | null;
+}
+export interface MaterializedNexusAgentSkill {
+    id: string;
+    name: string;
+    version: string;
+    materialization: NexusSkillMaterializationMode;
+    skillRoot: string;
+    skillPath: string | null;
+}
+export interface MaterializedNexusAgentSkillTarget {
+    agent: NexusSkillAgentId;
+    skillsDirectory: string;
+    sourceControl: NexusSkillSourceControl;
+    installed: MaterializedNexusAgentSkill[];
+}
+export interface MaterializeNexusProjectSkillsResult {
+    skillsDirectory: string;
+    installed: MaterializedNexusSkill[];
+    agentTargets: MaterializedNexusAgentSkillTarget[];
+    gitExcludePath: string | null;
+    gitExcludeEntries: string[];
+}
+export type NexusProjectSkillState = "installed" | "missing" | "stale" | "unexpected" | "invalid";
+export interface NexusProjectSkillStatus {
+    id: string;
+    state: NexusProjectSkillState;
+    expected: boolean;
+    installed: boolean;
+    name: string | null;
+    expectedVersion: string | null;
+    installedVersion: string | null;
+    materialization: NexusSkillMaterializationMode | null;
+    sourceControl: NexusSkillSourceControl | null;
+    skillRoot: string;
+    manifestPath: string;
+    skillPath: string | null;
+    reasons: string[];
+}
+export interface NexusProjectSkillStatusSummary {
+    expected: number;
+    installed: number;
+    missing: number;
+    stale: number;
+    unexpected: number;
+    invalid: number;
+}
+export interface InspectNexusProjectSkillsOptions {
+    projectRoot: string;
+    skillsConfig?: NexusProjectSkillsConfig;
+    skillDefinitions?: NexusSkillDefinition[];
+}
+export interface InspectNexusProjectSkillsResult {
+    skillsDirectory: string;
+    summary: NexusProjectSkillStatusSummary;
+    skills: NexusProjectSkillStatus[];
+}
+export interface RefreshNexusProjectSkillsOptions extends MaterializeNexusProjectSkillsOptions {
+}
+export interface RefreshNexusProjectSkillsResult {
+    before: InspectNexusProjectSkillsResult;
+    materialized: MaterializeNexusProjectSkillsResult;
+    after: InspectNexusProjectSkillsResult;
+}
+export declare class NexusSkillError extends Error {
+    constructor(message: string);
+}
+export declare const defaultCoreSkillPack: readonly NexusSkillDefinition[];
+export declare function inspectNexusProjectSkills(options: InspectNexusProjectSkillsOptions): InspectNexusProjectSkillsResult;
+export declare function materializeNexusProjectSkills(options: MaterializeNexusProjectSkillsOptions): MaterializeNexusProjectSkillsResult;
+export declare function refreshNexusProjectSkills(options: RefreshNexusProjectSkillsOptions): RefreshNexusProjectSkillsResult;