methodology-m 0.3.1

package/dist-m/schemas/pat.schema.json

@@ -0,0 +1,161 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://methodology-m.dev/schemas/pat.schema.json",
+  "title": "M PAT (Provable Acceptance Test)",
+  "description": "Schema for story-level and sub-task-level PAT.yaml files. Story PATs define the full acceptance contract for a user story. Sub-task PATs scope acceptance criteria to what is verifiable in isolation for a single component.",
+
+  "type": "object",
+  "required": ["version", "acceptance"],
+
+  "oneOf": [
+    {
+      "description": "Story-level PAT — lives in root repo at pats/<story-id>.pat.yaml",
+      "required": ["story"],
+      "properties": {
+        "story": true,
+        "version": true,
+        "acceptance": true
+      },
+      "not": {
+        "anyOf": [
+          { "required": ["sub-task"] },
+          { "required": ["parent-story"] },
+          { "required": ["component"] }
+        ]
+      }
+    },
+    {
+      "description": "Sub-task PAT — lives in managed repo at pats/<sub-task-id>.pat.yaml",
+      "required": ["sub-task", "parent-story", "component"],
+      "properties": {
+        "sub-task": true,
+        "parent-story": true,
+        "component": true,
+        "version": true,
+        "acceptance": true
+      },
+      "not": {
+        "required": ["story"]
+      }
+    }
+  ],
+
+  "properties": {
+    "story": {
+      "type": "string",
+      "description": "Story identifier (e.g. TODOM-001, PROJ-042). Present on story-level PATs only.",
+      "pattern": "^[A-Z]+-\\d+$"
+    },
+    "sub-task": {
+      "type": "string",
+      "description": "Sub-task identifier (e.g. TODOM-001c). Story ID + alphabetic suffix. Present on sub-task PATs only.",
+      "pattern": "^[A-Z]+-\\d+[a-z]$"
+    },
+    "parent-story": {
+      "type": "string",
+      "description": "Parent story identifier. Required on sub-task PATs.",
+      "pattern": "^[A-Z]+-\\d+$"
+    },
+    "component": {
+      "type": "string",
+      "description": "Component name from project.yaml (e.g. todo-m-mfe). Required on sub-task PATs."
+    },
+    "version": {
+      "type": "integer",
+      "description": "Schema version. Always 1 for now.",
+      "const": 1
+    },
+    "acceptance": {
+      "type": "array",
+      "description": "Ordered list of acceptance criteria. Order matters — later entries may depend on state created by earlier ones.",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/acceptance-criterion" }
+    }
+  },
+  "additionalProperties": false,
+
+  "$defs": {
+    "acceptance-criterion": {
+      "type": "object",
+      "required": ["id", "when", "then", "steps"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique within this PAT file. Format: AC-NNN for single criteria, AC-NNNx (a,b,c...) when one acceptance criterion yields multiple test scenarios.",
+          "pattern": "^AC-\\d{3}[a-z]?$"
+        },
+        "when": {
+          "type": "string",
+          "description": "Trigger condition in plain English. User-facing, topology-agnostic. No component names, API paths, or CSS selectors."
+        },
+        "then": {
+          "type": "string",
+          "description": "Expected outcome in plain English. Observable result from the user's perspective."
+        },
+        "steps": {
+          "type": "array",
+          "description": "Ordered test steps. Each step is an object with exactly one verb key. Steps map directly to Cypress commands for story-level PATs.",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/step" }
+        },
+        "replaces": {
+          "type": "string",
+          "description": "AC this supersedes, from a previous story. Format: <story-id>/AC-<id>. Compiler must find and update the old compiled test.",
+          "pattern": "^[A-Z]+-\\d+/AC-\\d{3}[a-z]?$"
+        },
+        "removes": {
+          "type": "string",
+          "description": "AC this deletes, from a previous story. Format: <story-id>/AC-<id>. Compiler must find and delete the old compiled test.",
+          "pattern": "^[A-Z]+-\\d+/AC-\\d{3}[a-z]?$"
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "step": {
+      "type": "object",
+      "description": "A single test step. Exactly one verb key per step object.",
+      "minProperties": 1,
+      "maxProperties": 1,
+      "oneOf": [
+        { "required": ["navigate"], "properties": { "navigate": { "$ref": "#/$defs/step-navigate" } } },
+        { "required": ["click"], "properties": { "click": { "$ref": "#/$defs/step-click" } } },
+        { "required": ["type"], "properties": { "type": { "$ref": "#/$defs/step-type" } } },
+        { "required": ["assert"], "properties": { "assert": { "$ref": "#/$defs/step-assert" } } },
+        { "required": ["wait"], "properties": { "wait": { "$ref": "#/$defs/step-wait" } } },
+        { "required": ["render"], "properties": { "render": { "$ref": "#/$defs/step-render" } } }
+      ]
+    },
+
+    "step-navigate": {
+      "type": "string",
+      "description": "Navigate to a URL path. Compiles to cy.visit(path).",
+      "examples": ["/", "/todos", "/login"]
+    },
+    "step-click": {
+      "type": "string",
+      "description": "Click an element by data-testid selector. Format: \"[data-testid='<id>']\". Compiles to cy.get(selector).click().",
+      "pattern": "^\"\\[data-testid='[^']+']\"$"
+    },
+    "step-type": {
+      "type": "string",
+      "description": "Type text into an element. Format: \"[data-testid='<id>']\" value \"<text>\". Compiles to cy.get(selector).type(text).",
+      "pattern": "^\"\\[data-testid='[^']+']\" value \"[^\"]*\"$"
+    },
+    "step-assert": {
+      "type": "string",
+      "description": "Assert a condition on an element. Formats: \"[selector]\" is visible | \"[selector]\" contains \"<value>\" | \"[selector]\" count > N | \"[selector]\" is disabled.",
+      "pattern": "^\"\\[data-testid='[^']+']\" (is visible|is disabled|contains \"[^\"]*\"|count > \\d+)$"
+    },
+    "step-wait": {
+      "type": "string",
+      "description": "Wait for a condition on an element. Same formats as assert but waits with retry. Compiles to cy.get(selector).should(...).",
+      "pattern": "^\"\\[data-testid='[^']+']\" (is visible|contains \"[^\"]*\")$"
+    },
+    "step-render": {
+      "type": "string",
+      "description": "Render a component with a mock setup. Sub-task PATs only (not browser-level). Not compiled to Cypress — used for component-level testing.",
+      "examples": ["Todo component with mocked API", "Todo component with empty mock API"]
+    }
+  }
+}

package/dist-m/schemas/project.schema.json

@@ -0,0 +1,177 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://methodology-m.dev/schemas/project.schema.json",
+  "title": "M project.yaml",
+  "description": "Schema for the topology manifest that lives at the root of every M-type root repo. Declares the project structure, components, providers, and configuration. Capabilities read this file to generate artefacts and resolve topology.",
+
+  "type": "object",
+  "required": ["project", "group", "components", "providers"],
+
+  "properties": {
+    "project": {
+      "type": "string",
+      "description": "Project name. Used as a prefix for managed repo names (e.g. project 'todo-m' yields 'todo-m-api-read')."
+    },
+    "group": {
+      "type": "string",
+      "description": "Full SCM group/org path (e.g. 'methodology-m/todo-m-workshop'). Used by scaffold-repo and wire-orchestration to resolve repo locations."
+    },
+    "topology": {
+      "type": "string",
+      "description": "Topology mode. 'distributed' places each component in its own repo. 'monolith-first' embeds all components in packages/ within the root repo.",
+      "enum": ["distributed", "monolith-first"],
+      "default": "distributed"
+    },
+
+    "providers": {
+      "type": "object",
+      "description": "Active providers by namespace. Capabilities call namespaced functions (e.g. scm.create_repo); the provider selected here determines the concrete implementation. See .m/providers/ for available providers.",
+      "required": ["scm"],
+      "properties": {
+        "scm": {
+          "type": "string",
+          "description": "Source code management provider. Determines which .m/providers/scm/<provider>.md file is used.",
+          "examples": ["gitlab", "github"]
+        }
+      },
+      "additionalProperties": {
+        "type": "string",
+        "description": "Future provider namespaces (e.g. ci, test, compose, deploy)."
+      }
+    },
+
+    "components": {
+      "type": "array",
+      "description": "Component catalogue. Ordered list — port assignment follows component order when ports are not explicit. The shell (frontend-host) is conventionally first.",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/component" }
+    },
+
+    "templates": {
+      "type": "object",
+      "description": "Template overrides per component role. Keys are roles, values are template-key or template-key@version from the org config catalogue. Omit to use defaults.",
+      "additionalProperties": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]+(\\@[\\w\\.]+)?$"
+      }
+    },
+
+    "pat-compilation": {
+      "type": "object",
+      "description": "Test framework per component role for PAT-to-CAT compilation. Omit to use M defaults (backend: supertest+vitest, frontend: cypress, frontend-host: cypress).",
+      "additionalProperties": {
+        "type": "string"
+      }
+    },
+
+    "persistence": {
+      "type": "object",
+      "description": "Shared state mechanism between components. Affects scaffold-repo (wires dependencies) and docker-compose.yml (volumes/services).",
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "Persistence mechanism key from config catalogue.",
+          "examples": ["sqlite", "postgres", "dynamodb-local"]
+        },
+        "volume": {
+          "type": "string",
+          "description": "Docker volume name for shared state."
+        }
+      },
+      "required": ["type"]
+    },
+
+    "compose": {
+      "type": "object",
+      "description": "System-level assembly configuration for AOT integration and local development.",
+      "properties": {
+        "local": {
+          "type": "object",
+          "description": "Local development compose strategy.",
+          "properties": {
+            "strategy": { "type": "string", "examples": ["process", "docker-compose"] },
+            "script": { "type": "string" },
+            "stop": { "type": "string" }
+          }
+        },
+        "integration": {
+          "type": "object",
+          "description": "CI AOT integration compose strategy.",
+          "properties": {
+            "strategy": {
+              "type": "string",
+              "description": "Compose strategy. Reference implementation is docker-compose.",
+              "examples": ["docker-compose", "kubernetes", "serverless"]
+            },
+            "file": { "type": "string", "description": "Compose file path relative to root repo." },
+            "build": { "type": "boolean", "description": "Whether to build images (true) or pull pre-built (false)." },
+            "health": {
+              "type": "object",
+              "properties": {
+                "timeout": { "type": "integer", "description": "Seconds to wait for all endpoints.", "default": 60 },
+                "endpoints": {
+                  "type": "array",
+                  "items": { "type": "string", "format": "uri" },
+                  "description": "Health check URLs. Derived from component ports and roles if omitted."
+                }
+              }
+            },
+            "tests": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "type": { "type": "string", "examples": ["cypress", "playwright", "k6"] },
+                  "spec": { "type": "string", "description": "Glob pattern for test files." },
+                  "base-url": { "type": "string", "format": "uri" }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+
+  "additionalProperties": false,
+
+  "$defs": {
+    "component": {
+      "type": "object",
+      "required": ["name", "type", "location"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Component identifier. Used in CI variable names (M_TOKEN_<NAME_UPPER>), compose service names, and repo name suffixes.",
+          "pattern": "^[a-z][a-z0-9-]+$"
+        },
+        "type": {
+          "type": "string",
+          "description": "'embedded' lives inside the root repo (packages/<name>). 'referenced' lives in its own repo.",
+          "enum": ["embedded", "referenced"]
+        },
+        "location": {
+          "type": "string",
+          "description": "For embedded: relative path (e.g. ./packages/shell). For referenced: full SCM path (e.g. methodology-m/todo-m-workshop/todo-m-api-read)."
+        },
+        "role": {
+          "type": "string",
+          "description": "Component role. Determines scaffold template, CI template, health check convention, and port defaults.",
+          "enum": ["frontend-host", "frontend", "backend"]
+        },
+        "tag": {
+          "type": ["string", "null"],
+          "description": "Version pin. Null (~) means nothing released yet. Set by auto-tag after merge transaction. Format: v<major>.<minor>.<patch>.",
+          "pattern": "^v\\d+\\.\\d+\\.\\d+$"
+        },
+        "port": {
+          "type": "integer",
+          "description": "Service port for compose and health checks. Convention: frontend-host=3000, frontend=3001, backends=3002+. If omitted, derived from component order and role.",
+          "minimum": 1,
+          "maximum": 65535
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "methodology-m",
+  "version": "0.3.1",
+  "description": "CLI for distributing Methodology M into AI-driven software projects",
+  "type": "module",
+  "bin": {
+    "m": "./bin/m.mjs",
+    "methodology-m": "./bin/m.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "dist-m/",
+    "templates/"
+  ],
+  "scripts": {
+    "snapshot": "node scripts/snapshot-dist.mjs",
+    "prepublishOnly": "node scripts/snapshot-dist.mjs",
+    "test": "node --test test/"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": ["methodology-m", "ai", "sdlc", "delivery", "multi-repo"],
+  "license": "MIT",
+  "author": "Textology Labs Ltd."
+}

package/src/commands/changelog.mjs

@@ -0,0 +1,58 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * m changelog [version]
+ * Print the bundled changelog, optionally filtered to a specific version.
+ */
+export async function changelog(args) {
+  const targetVersion = args[0];
+  const changelogPath = join(import.meta.dirname, '..', '..', 'dist-m', 'CHANGELOG.md');
+
+  if (!existsSync(changelogPath)) {
+    console.error('Changelog not found. Reinstall the CLI package.');
+    process.exit(1);
+  }
+
+  const content = readFileSync(changelogPath, 'utf8');
+
+  if (!targetVersion) {
+    console.log(content);
+    return;
+  }
+
+  // Extract the section for a specific version
+  const section = extractVersion(content, targetVersion);
+  if (section) {
+    console.log(section);
+  } else {
+    console.error(`Version ${targetVersion} not found in changelog.`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Extract a single version's section from a markdown changelog.
+ * Looks for ## [version] or ## version headings.
+ */
+function extractVersion(content, version) {
+  const lines = content.split('\n');
+  const normalized = version.replace(/^v/, '');
+  let capturing = false;
+  const result = [];
+
+  for (const line of lines) {
+    // Match ## [0.3.0], ## [v0.3.0], ## 0.3.0, etc.
+    if (line.match(/^## /)) {
+      if (capturing) break; // Hit the next version heading — stop
+      if (line.includes(normalized)) {
+        capturing = true;
+      }
+    }
+    if (capturing) {
+      result.push(line);
+    }
+  }
+
+  return result.length ? result.join('\n').trim() : null;
+}

package/src/commands/clone.mjs

@@ -0,0 +1,199 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import { join, basename, resolve } from 'node:path';
+import { execSync } from 'node:child_process';
+import { readTopology, getReferencedRepos } from '../lib/topology.mjs';
+import { generateWorkspace } from '../lib/workspace.mjs';
+
+/**
+ * m clone <root-repo-url> [--ide vscode]
+ * m clone                  (run from inside an existing root repo)
+ */
+export async function clone(args) {
+  const flags = parseFlags(args);
+  const ide = flags.ide || 'vscode';
+
+  if (flags.url) {
+    await cloneFromUrl(flags.url, ide);
+  } else {
+    await cloneFromExisting(ide);
+  }
+}
+
+async function cloneFromUrl(url, ide) {
+  // Derive the root repo directory name from the URL
+  const repoName = basename(url, '.git');
+
+  // Create a parent workspace directory named after the project
+  // We'll rename it after reading project.yaml if the project name differs
+  const parentDir = resolve(repoName + '-workspace');
+
+  if (existsSync(parentDir)) {
+    console.error(`Directory ${parentDir} already exists. Remove it or run "m clone" from inside the root repo.`);
+    process.exit(1);
+  }
+
+  mkdirSync(parentDir, { recursive: true });
+
+  // 1. Clone root repo
+  console.log(`Cloning root repo: ${url}`);
+  gitClone(url, join(parentDir, repoName));
+  console.log(`  ✓ ${repoName}/`);
+
+  // 2. Read topology
+  const rootDir = join(parentDir, repoName);
+  const topology = readTopology(rootDir);
+  const repos = getReferencedRepos(topology);
+
+  console.log(`  Project: ${topology.project} (${repos.length} managed repos)`);
+  console.log('');
+
+  // 3. Clone managed repos
+  const clonedDirs = [repoName];
+
+  for (const repo of repos) {
+    const repoDir = join(parentDir, repo.repoName);
+    if (existsSync(repoDir)) {
+      console.log(`  · ${repo.repoName}/ already exists (skipped)`);
+      clonedDirs.push(repo.repoName);
+      continue;
+    }
+
+    // Derive clone URL from root URL pattern + component location
+    const cloneUrl = deriveCloneUrl(url, repo.location);
+    console.log(`  Cloning ${repo.repoName}...`);
+    gitClone(cloneUrl, repoDir);
+    console.log(`  ✓ ${repo.repoName}/`);
+    clonedDirs.push(repo.repoName);
+  }
+
+  // 4. Generate workspace file
+  console.log('');
+  const wsPath = generateWorkspace(parentDir, topology.project, clonedDirs, { ide });
+  console.log(`  ✓ ${basename(wsPath)} generated`);
+
+  // 5. Summary
+  printSummary(parentDir, topology.project, clonedDirs, wsPath, ide);
+}
+
+async function cloneFromExisting(ide) {
+  // Assume we're inside the root repo — find project.yaml
+  const cwd = process.cwd();
+  let rootDir = cwd;
+
+  if (!existsSync(join(rootDir, 'project.yaml'))) {
+    console.error('No project.yaml found. Run this from inside the root repo, or provide a URL: m clone <url>');
+    process.exit(1);
+  }
+
+  const parentDir = resolve(rootDir, '..');
+  const repoName = basename(rootDir);
+
+  const topology = readTopology(rootDir);
+  const repos = getReferencedRepos(topology);
+
+  console.log(`Project: ${topology.project} (${repos.length} managed repos)`);
+  console.log('');
+
+  const clonedDirs = [repoName];
+
+  for (const repo of repos) {
+    const repoDir = join(parentDir, repo.repoName);
+    if (existsSync(repoDir)) {
+      console.log(`  · ${repo.repoName}/ already exists (skipped)`);
+      clonedDirs.push(repo.repoName);
+      continue;
+    }
+
+    // Try to derive URL from root repo's remote
+    const rootRemote = getGitRemote(rootDir);
+    if (!rootRemote) {
+      console.error(`  ✗ Cannot determine clone URL for ${repo.repoName} — root repo has no remote`);
+      continue;
+    }
+
+    const cloneUrl = deriveCloneUrl(rootRemote, repo.location);
+    console.log(`  Cloning ${repo.repoName}...`);
+    gitClone(cloneUrl, repoDir);
+    console.log(`  ✓ ${repo.repoName}/`);
+    clonedDirs.push(repo.repoName);
+  }
+
+  // Generate workspace file
+  console.log('');
+  const wsPath = generateWorkspace(parentDir, topology.project, clonedDirs, { ide });
+  console.log(`  ✓ ${basename(wsPath)} generated`);
+
+  printSummary(parentDir, topology.project, clonedDirs, wsPath, ide);
+}
+
+function gitClone(url, dest) {
+  execSync(`git clone "${url}" "${dest}"`, { stdio: 'pipe' });
+}
+
+function getGitRemote(repoDir) {
+  try {
+    return execSync('git remote get-url origin', { cwd: repoDir, stdio: 'pipe' })
+      .toString()
+      .trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Derive a clone URL for a managed repo from the root repo URL and the
+ * component location in project.yaml.
+ *
+ * Root URL: git@gitlab.com:acme/todo-m-workshop/todo-m-root.git
+ * Location: acme/todo-m-workshop/todo-m-api-read
+ * Result:   git@gitlab.com:acme/todo-m-workshop/todo-m-api-read.git
+ *
+ * Supports both SSH (git@host:path) and HTTPS (https://host/path) formats.
+ */
+function deriveCloneUrl(rootUrl, location) {
+  // SSH format: git@gitlab.com:group/subgroup/repo.git
+  const sshMatch = rootUrl.match(/^(git@[^:]+:)/);
+  if (sshMatch) {
+    return `${sshMatch[1]}${location}.git`;
+  }
+
+  // HTTPS format: https://gitlab.com/group/subgroup/repo.git
+  const httpsMatch = rootUrl.match(/^(https?:\/\/[^/]+)\//);
+  if (httpsMatch) {
+    return `${httpsMatch[1]}/${location}.git`;
+  }
+
+  // Fallback: just replace the last path segment
+  throw new Error(
+    `Cannot derive clone URL for "${location}" from root URL "${rootUrl}". ` +
+    `Provide the full URL manually.`
+  );
+}
+
+function parseFlags(args) {
+  const flags = { url: null, ide: null };
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--ide' && args[i + 1]) {
+      flags.ide = args[++i];
+    } else if (!args[i].startsWith('-')) {
+      flags.url = args[i];
+    }
+  }
+
+  return flags;
+}
+
+function printSummary(parentDir, projectName, dirs, wsPath, ide) {
+  console.log('');
+  console.log(`Workspace ready at ${parentDir}/`);
+  console.log('');
+  for (const d of dirs) console.log(`  ${d}/`);
+  console.log(`  ${basename(wsPath)}`);
+  console.log('');
+
+  if (ide === 'vscode') {
+    console.log(`Open in VS Code:`);
+    console.log(`  code ${wsPath}`);
+  }
+}

package/src/commands/diff.mjs

@@ -0,0 +1,29 @@
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { readInstalledVersion, readAvailableVersion } from '../lib/version-file.mjs';
+import { diffTrees, formatDiff } from '../lib/diff-trees.mjs';
+
+export async function diff(args) {
+  const target = resolve(args[0] || '.');
+  const installed = readInstalledVersion(target);
+  const available = readAvailableVersion();
+
+  if (!installed) {
+    console.error('M is not installed in this project. Run "m init" first.');
+    process.exit(1);
+  }
+
+  const installedDir = join(target, '.m');
+  const availableDir = join(import.meta.dirname, '..', '..', 'dist-m');
+
+  if (!existsSync(availableDir)) {
+    console.error('dist-m/ not found. Reinstall the CLI package.');
+    process.exit(1);
+  }
+
+  console.log(`Comparing installed v${installed} against available v${available}`);
+  console.log('');
+
+  const result = diffTrees(installedDir, availableDir);
+  console.log(formatDiff(result));
+}