@flancer32/skill-adsm-ctx 0.2.1

package/src/Init/Service.mjs

@@ -0,0 +1,136 @@
+// @ts-check
+
+/**
+ * @namespace Fl32_Skill_Adsm_Ctx_Init_Service
+ * @description Initializes the baseline ADSM context structure in a target project directory.
+ */
+
+const templateRoot = new URL("../../skill/templates/ctx/", import.meta.url);
+const rootAgentsTemplate = [
+  "# Root Level",
+  "",
+  "- Path: `AGENTS.md`",
+  "- Changed: `20260702`",
+  "",
+  "## Purpose",
+  "",
+  "Marks the repository root and points agents to the project cognitive context in `ctx/`.",
+  "",
+  "## Bootstrap Exception",
+  "",
+  "- `init` and other bootstrap operations may create the initial `ctx/` structure when it does not exist yet.",
+  "- This repository uses an ADSM-managed cognitive context.",
+  "- Use skill `adsm-ctx` for context validation, upgrades, and methodology rules.",
+  "",
+  "## Cognitive Context Entry",
+  "",
+  "- Read `ctx/AGENTS.md` before modifying project files after the context exists.",
+  "- Treat `ctx/` as the source of truth for project context after bootstrap is complete.",
+  "",
+].join("\n");
+
+export default class Service {
+  /**
+   * @param {object} deps
+   * @param {Fl32_Skill_Adsm_Ctx_Shared_CopyDirectory} deps.copyDirectory
+   * @param {typeof import("node:fs")} deps.fs
+   * @param {Fl32_Skill_Adsm_Ctx_Shared_Metadata} deps.metadata
+   * @param {Fl32_Skill_Adsm_Ctx_Shared_Path} deps.pathService
+   * @param {typeof import("node:url")} deps.url
+   */
+  constructor({copyDirectory, fs, metadata, pathService, url}) {
+    /**
+     * Creates baseline context structure in the target project.
+     *
+     * @param {object} params
+     * @param {string} params.targetPath
+     * @returns {Promise<{created: string[], ctxRoot: string, projectRoot: string, skipped: string[]}>}
+     */
+    this.execute = async function ({targetPath}) {
+      const projectRoot = pathService.resolve(targetPath);
+      const ctxRoot = pathService.join(projectRoot, "ctx");
+      const created = [];
+      const skipped = [];
+
+      fs.mkdirSync(projectRoot, {recursive: true});
+      copyDirectory.copyMissing({
+        sourcePath: url.fileURLToPath(templateRoot),
+        targetPath: ctxRoot,
+        created,
+        pathPrefix: "ctx",
+        skipped,
+      });
+      stampCreatedMarkdownDates({created, fs, pathService, projectRoot});
+      ensureRootAgents({created, fs, pathService, projectRoot, skipped});
+      writeMetadata({created, fs, metadata, pathService, projectRoot, skipped});
+
+      return {created, ctxRoot, projectRoot, skipped};
+    };
+  }
+}
+
+/**
+ * @param {object} params
+ * @param {string[]} params.created
+ * @param {typeof import("node:fs")} params.fs
+ * @param {Fl32_Skill_Adsm_Ctx_Shared_Path} params.pathService
+ * @param {string} params.projectRoot
+ * @param {string[]} params.skipped
+ * @returns {void}
+ */
+function ensureRootAgents({created, fs, pathService, projectRoot, skipped}) {
+  const filePath = pathService.join(projectRoot, "AGENTS.md");
+  if (!fs.existsSync(filePath)) {
+    fs.writeFileSync(filePath, rootAgentsTemplate);
+    created.push("AGENTS.md");
+  } else {
+    skipped.push("AGENTS.md");
+  }
+}
+
+/**
+ * @param {object} params
+ * @param {string[]} params.created
+ * @param {typeof import("node:fs")} params.fs
+ * @param {Fl32_Skill_Adsm_Ctx_Shared_Path} params.pathService
+ * @param {string} params.projectRoot
+ * @returns {void}
+ */
+function stampCreatedMarkdownDates({created, fs, pathService, projectRoot}) {
+  const currentDate = new Date().toISOString().slice(0, 10).replaceAll("-", "");
+  for (const entry of created) {
+    if (!entry.endsWith(".md")) continue;
+    const filePath = pathService.join(projectRoot, ...entry.split("/"));
+    const current = fs.readFileSync(filePath, "utf8");
+    const updated = current.replace(/- Changed: `YYYYMMDD`/g, `- Changed: \`${currentDate}\``);
+    if (updated !== current) fs.writeFileSync(filePath, updated);
+  }
+}
+
+/**
+ * @param {object} params
+ * @param {string[]} params.created
+ * @param {typeof import("node:fs")} params.fs
+ * @param {Fl32_Skill_Adsm_Ctx_Shared_Metadata} params.metadata
+ * @param {Fl32_Skill_Adsm_Ctx_Shared_Path} params.pathService
+ * @param {string} params.projectRoot
+ * @param {string[]} params.skipped
+ * @returns {void}
+ */
+function writeMetadata({created, fs, metadata, pathService, projectRoot, skipped}) {
+  const metadataPath = pathService.join(projectRoot, "ctx", "adsm.json");
+  if (!fs.existsSync(metadataPath)) {
+    fs.writeFileSync(metadataPath, `${JSON.stringify(metadata.create(), null, 2)}\n`);
+    created.push("ctx/adsm.json");
+  } else {
+    skipped.push("ctx/adsm.json");
+  }
+}
+
+export const __deps__ = Object.freeze({
+  copyDirectory: "Fl32_Skill_Adsm_Ctx_Shared_CopyDirectory$",
+  fs: "node:fs",
+  metadata: "Fl32_Skill_Adsm_Ctx_Shared_Metadata$",
+  pathService: "Fl32_Skill_Adsm_Ctx_Shared_Path$",
+  url: "node:url",
+});

package/src/Shared/Constants.mjs

@@ -0,0 +1,36 @@
+// @ts-check
+
+/**
+ * @namespace Fl32_Skill_Adsm_Ctx_Shared_Constants
+ * @description Publishes immutable baseline constants for the ADSM context lifecycle package.
+ */
+
+export default class Constants {
+  constructor() {
+    this.CONTEXT_SCHEMA = "adsm-context";
+    this.CONTEXT_VERSION = "0.1.0";
+    this.SKIN_WORD_WARN = 160;
+    this.SKIN_WORD_ERROR = 240;
+    this.SKIN_LIST_WARN = 12;
+    this.SKIN_LIST_ERROR = 20;
+    this.DOC_LEVEL_MAX_DIRECTORIES = 9;
+    this.DOC_LEVEL_MAX_FILES = 9;
+    this.REQUIRED_PATHS = Object.freeze([
+      "AGENTS.md",
+      "ctx",
+      "ctx/docs",
+      "ctx/docs/product",
+      "ctx/docs/architecture",
+      "ctx/docs/environment",
+      "ctx/docs/code",
+      "ctx/adsm.json",
+      "ctx/AGENTS.md",
+      "ctx/docs/AGENTS.md",
+      "ctx/docs/product/AGENTS.md",
+      "ctx/docs/architecture/AGENTS.md",
+      "ctx/docs/environment/AGENTS.md",
+      "ctx/docs/code/AGENTS.md",
+    ]);
+    this.DOC_LEVELS = Object.freeze(["product", "architecture", "environment", "code"]);
+  }
+}

package/src/Shared/CopyDirectory.mjs

@@ -0,0 +1,78 @@
+// @ts-check
+
+/**
+ * @namespace Fl32_Skill_Adsm_Ctx_Shared_CopyDirectory
+ * @description Recursively copies a directory tree using Node.js filesystem primitives.
+ */
+
+export default class CopyDirectory {
+  /**
+   * @param {object} deps
+   * @param {typeof import("node:fs")} deps.fs
+   * @param {Fl32_Skill_Adsm_Ctx_Shared_Path} deps.pathService
+   */
+  constructor({fs, pathService}) {
+    /**
+     * Copies a directory tree recursively.
+     *
+     * @param {object} params
+     * @param {string} params.sourcePath
+     * @param {string} params.targetPath
+     * @returns {void}
+     */
+    this.execute = function ({sourcePath, targetPath}) {
+      fs.mkdirSync(targetPath, {recursive: true});
+      for (const entry of fs.readdirSync(sourcePath, {withFileTypes: true})) {
+        const sourceEntry = pathService.join(sourcePath, entry.name);
+        const targetEntry = pathService.join(targetPath, entry.name);
+        if (entry.isDirectory()) {
+          this.execute({sourcePath: sourceEntry, targetPath: targetEntry});
+        } else {
+          fs.copyFileSync(sourceEntry, targetEntry);
+        }
+      }
+    };
+
+    /**
+     * Copies only missing directories and files from source to target.
+     *
+     * @param {object} params
+     * @param {string[]} params.created
+     * @param {string} params.pathPrefix
+     * @param {string[]} params.skipped
+     * @param {string} params.sourcePath
+     * @param {string} params.targetPath
+     * @returns {void}
+     */
+    this.copyMissing = function ({created, pathPrefix, skipped, sourcePath, targetPath}) {
+      if (!fs.existsSync(targetPath)) {
+        fs.mkdirSync(targetPath, {recursive: true});
+        if (pathPrefix) created.push(pathPrefix);
+      }
+      for (const entry of fs.readdirSync(sourcePath, {withFileTypes: true})) {
+        const sourceEntry = pathService.join(sourcePath, entry.name);
+        const targetEntry = pathService.join(targetPath, entry.name);
+        const relativePath = pathPrefix ? pathService.join(pathPrefix, entry.name) : entry.name;
+        if (entry.isDirectory()) {
+          this.copyMissing({
+            created,
+            pathPrefix: relativePath,
+            skipped,
+            sourcePath: sourceEntry,
+            targetPath: targetEntry,
+          });
+        } else if (!fs.existsSync(targetEntry)) {
+          fs.copyFileSync(sourceEntry, targetEntry);
+          created.push(relativePath);
+        } else {
+          skipped.push(relativePath);
+        }
+      }
+    };
+  }
+}
+
+export const __deps__ = Object.freeze({
+  fs: "node:fs",
+  pathService: "Fl32_Skill_Adsm_Ctx_Shared_Path$",
+});

package/src/Shared/Metadata.mjs

@@ -0,0 +1,30 @@
+// @ts-check
+
+/**
+ * @namespace Fl32_Skill_Adsm_Ctx_Shared_Metadata
+ * @description Creates baseline ADSM context metadata payloads.
+ */
+
+export default class Metadata {
+  /**
+   * @param {object} deps
+   * @param {Fl32_Skill_Adsm_Ctx_Shared_Constants} deps.constants
+   */
+  constructor({constants}) {
+    /**
+     * Creates the baseline metadata object.
+     *
+     * @returns {{schema: string, version: string}}
+     */
+    this.create = function () {
+      return {
+        schema: constants.CONTEXT_SCHEMA,
+        version: constants.CONTEXT_VERSION,
+      };
+    };
+  }
+}
+
+export const __deps__ = Object.freeze({
+  constants: "Fl32_Skill_Adsm_Ctx_Shared_Constants$",
+});

package/src/Shared/Path.mjs

@@ -0,0 +1,38 @@
+// @ts-check
+
+/**
+ * @namespace Fl32_Skill_Adsm_Ctx_Shared_Path
+ * @description Resolves filesystem paths using the Node.js path module.
+ */
+
+export default class Path {
+  /**
+   * @param {object} deps
+   * @param {typeof import("node:path")} deps.path
+   */
+  constructor({path}) {
+    /**
+     * Resolves a path to an absolute path.
+     *
+     * @param {string} targetPath
+     * @returns {string}
+     */
+    this.resolve = function (targetPath) {
+      return path.resolve(targetPath);
+    };
+
+    /**
+     * Joins path segments.
+     *
+     * @param {...string} parts
+     * @returns {string}
+     */
+    this.join = function (...parts) {
+      return path.join(...parts);
+    };
+  }
+}
+
+export const __deps__ = Object.freeze({
+  path: "node:path",
+});

package/src/Skill/Installer.mjs

@@ -0,0 +1,47 @@
+// @ts-check
+
+/**
+ * @namespace Fl32_Skill_Adsm_Ctx_Skill_Installer
+ * @description Installs the bundled skill payload into a target skills directory.
+ */
+
+const sourceRoot = new URL("../../skill/", import.meta.url);
+
+export default class Installer {
+  /**
+   * @param {object} deps
+   * @param {Fl32_Skill_Adsm_Ctx_Shared_CopyDirectory} deps.copyDirectory
+   * @param {typeof import("node:fs")} deps.fs
+   * @param {Fl32_Skill_Adsm_Ctx_Shared_Path} deps.pathService
+   * @param {typeof import("node:url")} deps.url
+   */
+  constructor({copyDirectory, fs, pathService, url}) {
+    /**
+     * Installs the skill payload.
+     *
+     * @param {object} params
+     * @param {string} params.targetRoot
+     * @returns {Promise<string>}
+     */
+    this.execute = async function ({targetRoot}) {
+      if (!targetRoot) {
+        throw new Error("Target skills directory is required.");
+      }
+
+      const targetDir = pathService.join(pathService.resolve(targetRoot), "adsm-ctx");
+      fs.rmSync(targetDir, {recursive: true, force: true});
+      copyDirectory.execute({
+        sourcePath: url.fileURLToPath(sourceRoot),
+        targetPath: targetDir,
+      });
+      return targetDir;
+    };
+  }
+}
+
+export const __deps__ = Object.freeze({
+  copyDirectory: "Fl32_Skill_Adsm_Ctx_Shared_CopyDirectory$",
+  fs: "node:fs",
+  pathService: "Fl32_Skill_Adsm_Ctx_Shared_Path$",
+  url: "node:url",
+});

package/src/Upgrade/Service.mjs

@@ -0,0 +1,44 @@
+// @ts-check
+
+/**
+ * @namespace Fl32_Skill_Adsm_Ctx_Upgrade_Service
+ * @description Provides the baseline non-destructive upgrade entry point for ADSM context lifecycle.
+ */
+
+export default class Service {
+  /**
+   * @param {object} deps
+   * @param {typeof import("node:fs")} deps.fs
+   * @param {Fl32_Skill_Adsm_Ctx_Shared_Path} deps.pathService
+   */
+  constructor({fs, pathService}) {
+    /**
+     * Runs the upgrade entry point.
+     *
+     * @param {object} params
+     * @param {string} params.targetPath
+     * @returns {Promise<{message: string, ok: boolean}>}
+     */
+    this.execute = async function ({targetPath}) {
+      const projectRoot = pathService.resolve(targetPath);
+      const metadataPath = pathService.join(projectRoot, "ctx", "adsm.json");
+
+      if (!fs.existsSync(metadataPath)) {
+        return {
+          message: "No ADSM context metadata found. Run `adsm-ctx init` before upgrade.",
+          ok: false,
+        };
+      }
+
+      return {
+        message: "No migrations are currently available for this context.",
+        ok: true,
+      };
+    };
+  }
+}
+
+export const __deps__ = Object.freeze({
+  fs: "node:fs",
+  pathService: "Fl32_Skill_Adsm_Ctx_Shared_Path$",
+});