@geraldmaron/construct 1.0.7 → 1.0.8

package/lib/overrides/resolver.mjs

@@ -38,11 +38,11 @@ export const SUPPORTED_CATEGORIES = Object.freeze([
 
 const CATEGORY_RULES = {
   personas: { originalDir: 'personas', defaultExt: '.md' },
-  agents: { originalDir: 'agents/prompts', defaultExt: '.md' },
+  agents: { originalDir: 'specialists/prompts', defaultExt: '.md' },
   skills: { originalDir: 'skills', defaultExt: '.md' },
   rules: { originalDir: 'rules', defaultExt: '.md' },
-  contracts: { originalDir: 'agents', defaultExt: '.json', singleFile: 'contracts.json' },
-  'role-manifests': { originalDir: 'agents', defaultExt: '.json', singleFile: 'role-manifests.json' },
+  contracts: { originalDir: 'specialists', defaultExt: '.json', singleFile: 'contracts.json' },
+  'role-manifests': { originalDir: 'specialists', defaultExt: '.json', singleFile: 'role-manifests.json' },
 };
 
 function categoryRule(category) {

package/lib/parity.mjs

@@ -3,7 +3,7 @@
  *
  * After `construct sync` writes adapters to multiple surfaces (Claude Code,
  * OpenCode, Codex, Copilot, VS Code, Cursor), the module diffs each surface's actual state against the
- * canonical `agents/registry.json`. Backs `construct doctor` for surfacing
+ * canonical `specialists/registry.json`. Backs `construct doctor` for surfacing
  * silent divergence — for instance, an agent added to the registry that
  * never made it to OpenCode because of a sync regression.
  *
@@ -31,7 +31,7 @@ const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
 const ROOT_DIR = path.resolve(MODULE_DIR, '..');
 
 function loadRegistry(rootDir = ROOT_DIR) {
-  const file = path.join(rootDir, 'agents', 'registry.json');
+  const file = path.join(rootDir, 'specialists', 'registry.json');
   return JSON.parse(fs.readFileSync(file, 'utf8'));
 }
 
@@ -42,8 +42,8 @@ function adapterName(entry, prefix) {
 function entriesForSurface(registry, surface) {
   const prefix = registry.prefix || 'cx';
   const entries = [
-    ...(registry.personas || []).map((p) => ({ ...p, isPersona: true })),
-    ...(registry.agents || []).map((a) => ({ ...a, isPersona: false })),
+    ...(registry.orchestrator ? [{ ...registry.orchestrator, isPersona: true }] : []),
+    ...(registry.specialists || []).map((s) => ({ ...s, isPersona: false })),
   ];
 
   return entries

package/lib/policy/engine.mjs

@@ -1,7 +1,7 @@
 /**
  * lib/policy/engine.mjs — role-based policy decisions for tool / action access.
  *
- * Reads role permissions from `agents/role-manifests.json` and decides
+ * Reads role permissions from `specialists/role-manifests.json` and decides
  * whether a given (role, project, tool, action, risk) tuple is allowed,
  * needs approval, or is denied outright. Powers the MCP broker for team
  * and enterprise deployments; solo mode leaves the broker off so this
@@ -20,7 +20,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
-const DEFAULT_MANIFEST_PATH = path.join(MODULE_DIR, '..', '..', 'agents', 'role-manifests.json');
+const DEFAULT_MANIFEST_PATH = path.join(MODULE_DIR, '..', '..', 'specialists', 'role-manifests.json');
 
 const HIGH_RISK_AUTONOMOUS = new Set(['security', 'sre', 'release-manager']);
 

package/lib/profiles/lifecycle.mjs

@@ -76,7 +76,7 @@ Goal: define the role set and how it interlocks with the curated cx-* registry.
   reuse-existing (name the cx-* agent), create-new (specify scope), or compose-overlay (which base role + which flavor).
 - Identify cross-role handoffs. Where can ambiguity stall the loop? Name the orchestrator role.
 - Validate against the per-role cap (max 6 flavors per role per profile).
-- Acceptance: every declared role either exists in agents/registry.json or has a written scope statement.
+- Acceptance: every declared role either exists in specialists/registry.json or has a written scope statement.
 
 ## 4. Validation (cx-evaluator)
 

package/lib/prompt-metadata.mjs

@@ -25,9 +25,9 @@ function normalizeName(name) {
 function findEntry(registry, agentName) {
   const normalized = normalizeName(agentName);
   const entries = [
-    ...(registry.personas ?? []),
-    ...(registry.agents ?? []),
-  ];
+    registry.orchestrator,
+    ...(registry.specialists ?? []),
+  ].filter(Boolean);
   return entries.find((entry) => {
     const entryName = normalizeName(entry.name);
     return entryName === normalized || `cx-${entryName}` === String(agentName ?? '').trim().toLowerCase();
@@ -36,7 +36,7 @@ function findEntry(registry, agentName) {
 
 export function resolvePromptEntry(agentName, { rootDir = process.cwd(), registry } = {}) {
   if (!agentName) return null;
-  const loadedRegistry = registry ?? readJson(path.join(rootDir, 'agents', 'registry.json'));
+  const loadedRegistry = registry ?? readJson(path.join(rootDir, 'specialists', 'registry.json'));
   if (!loadedRegistry) return null;
   return findEntry(loadedRegistry, agentName);
 }

package/lib/providers/circuit-breaker.mjs

@@ -104,6 +104,20 @@ export function getBreaker(key, options) {
   return REGISTRY.get(key);
 }
 
+export function getState(providerName) {
+  const b = REGISTRY.get(providerName);
+  if (!b) return null;
+  return {
+    state: b.state.toUpperCase(),
+    failures: b.failureCount,
+    lastFailure: b.openedAt ? new Date(b.openedAt) : null,
+  };
+}
+
+export function reset(providerName) {
+  REGISTRY.get(providerName)?.reset();
+}
+
 export function describeBreakers() {
   return [...REGISTRY.values()].map((b) => ({
     key: b.key,

package/lib/providers/contract.mjs

@@ -3,7 +3,7 @@
  *
  * A provider integrates Construct with an external system that holds work
  * artefacts: GitHub repos, Jira projects, Confluence spaces, Slack channels,
- * Salesforce orgs, etc. Providers are stateless adapters — durable state
+ * Salesforce orgs, etc. Providers are stateless adapters; durable state
  * (cached search results, last-seen markers, observations distilled from
  * fetched items) lives in core stores, not in the provider.
  *
@@ -29,11 +29,75 @@
  *
  * `assertProviderContract(provider)` runs at registry load time and refuses
  * to accept providers that miss required fields or declare capabilities
- * they don't implement. The check is deliberately loose — providers can
- * extend the shape with extra methods — but it gates the load-bearing
+ * they don't implement. The check is deliberately loose; providers can
+ * extend the shape with extra methods; but it gates the load-bearing
  * fields so a typo in a plugin can't take down the registry.
+ *
+ * Scope validation: `ALLOWLIST_SCHEMA` declares the allowlist fields
+ * supported per provider. `validateAllowlist(providerName, target, config)`
+ * checks whether `target` (a repo name, channel ID, project key, etc.) is
+ * permitted by the caller's config. When no allowlist fields are set the
+ * call is allowed through; when any allowlist field is set the target must
+ * satisfy it.
+ *
+ * Glob matching for `*Glob` fields follows minimatch-style single-segment
+ * patterns where `*` matches any sequence of non-slash characters.
  */
 
+export const ALLOWLIST_SCHEMA = Object.freeze({
+  github:                 { fields: ['org', 'repoAllowlist', 'repoAllowGlob'] },
+  'atlassian-jira':       { fields: ['instance', 'projectAllowlist'] },
+  'atlassian-confluence': { fields: ['instance', 'spaceAllowlist'] },
+  slack:                  { fields: ['workspace', 'channelAllowlist'] },
+  salesforce:             { fields: ['instance', 'objectAllowlist'] },
+});
+
+function globMatch(pattern, value) {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*');
+  return new RegExp(`^${escaped}$`).test(value);
+}
+
+export function validateAllowlist(providerName, target, config = {}) {
+  const schema = ALLOWLIST_SCHEMA[providerName];
+
+  // Unknown providers pass through; no schema means no restriction.
+  if (!schema) return { allowed: true, reason: 'no allowlist schema for provider' };
+
+  const listFields = schema.fields.filter((f) => f.endsWith('Allowlist'));
+  const globFields = schema.fields.filter((f) => f.endsWith('AllowGlob'));
+
+  const hasListConstraint = listFields.some((f) => Array.isArray(config[f]) && config[f].length > 0);
+  const hasGlobConstraint = globFields.some((f) => typeof config[f] === 'string' && config[f].length > 0);
+
+  // No allowlist configured: permit everything.
+  if (!hasListConstraint && !hasGlobConstraint) {
+    return { allowed: true, reason: 'no allowlist configured' };
+  }
+
+  // Check explicit list membership.
+  for (const field of listFields) {
+    if (Array.isArray(config[field]) && config[field].length > 0) {
+      if (config[field].includes(target)) {
+        return { allowed: true, reason: `matched ${field}` };
+      }
+    }
+  }
+
+  // Check glob patterns.
+  for (const field of globFields) {
+    if (typeof config[field] === 'string' && config[field].length > 0) {
+      if (globMatch(config[field], target)) {
+        return { allowed: true, reason: `matched ${field} pattern '${config[field]}'` };
+      }
+    }
+  }
+
+  return {
+    allowed: false,
+    reason: `'${target}' is not in the configured allowlist for ${providerName}`,
+  };
+}
+
 export const CAPABILITIES = Object.freeze([
   'read',
   'search',

package/lib/providers/creds.mjs

@@ -0,0 +1,219 @@
+/**
+ * lib/providers/creds.mjs — credential management for provider integrations.
+ *
+ * Reads and writes provider credentials stored in `~/.construct/config.env`.
+ * Each provider block is delimited by comment markers so the file can be
+ * parsed without a full ini/dotenv library and can also be sourced by a shell.
+ *
+ * Block format (example for `github`):
+ *
+ *   # CONSTRUCT_CREDS_GITHUB
+ *   CONSTRUCT_CREDS_GITHUB_KEY=ghp_xxx
+ *   CONSTRUCT_CREDS_GITHUB_ACCOUNT=myorg
+ *   CONSTRUCT_CREDS_GITHUB_ROTATED_AT=2026-05-27
+ *   # END_CONSTRUCT_CREDS_GITHUB
+ *
+ * Security: `writeCreds` sets the file mode to 0600 after every write.
+ * `checkCredsFileMode` reports whether the current mode is within policy.
+ *
+ * All functions are synchronous except those that need the filesystem and
+ * are documented as async. Currently all ops are sync; the async signature
+ * is reserved for future keychain-backend support.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const CONSTRUCT_DIR = path.join(os.homedir(), '.construct');
+const CONFIG_FILE = 'config.env';
+
+export function credsFilePath() {
+  return path.join(CONSTRUCT_DIR, CONFIG_FILE);
+}
+
+function providerKey(provider) {
+  return provider.toUpperCase().replace(/-/g, '_');
+}
+
+function blockStart(key) {
+  return `# CONSTRUCT_CREDS_${key}`;
+}
+
+function blockEnd(key) {
+  return `# END_CONSTRUCT_CREDS_${key}`;
+}
+
+function readRaw() {
+  const fp = credsFilePath();
+  try {
+    return fs.readFileSync(fp, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return '';
+    throw err;
+  }
+}
+
+function writeRaw(content) {
+  const fp = credsFilePath();
+  fs.mkdirSync(path.dirname(fp), { recursive: true });
+  fs.writeFileSync(fp, content, { encoding: 'utf8', mode: 0o600 });
+
+  // Re-apply mode after write; some platforms reset on open.
+  fs.chmodSync(fp, 0o600);
+}
+
+function extractBlocks(raw) {
+  const blocks = {};
+  const lines = raw.split('\n');
+  let current = null;
+  let currentLines = [];
+
+  for (const line of lines) {
+    const startMatch = line.match(/^# CONSTRUCT_CREDS_([A-Z0-9_]+)$/);
+    const endMatch = line.match(/^# END_CONSTRUCT_CREDS_([A-Z0-9_]+)$/);
+
+    if (startMatch) {
+      current = startMatch[1];
+      currentLines = [line];
+      continue;
+    }
+    if (endMatch && current === endMatch[1]) {
+      currentLines.push(line);
+      blocks[current] = currentLines.join('\n');
+      current = null;
+      currentLines = [];
+      continue;
+    }
+    if (current) {
+      currentLines.push(line);
+    }
+  }
+
+  return blocks;
+}
+
+function parseBlock(blockText) {
+  const result = {};
+  for (const line of blockText.split('\n')) {
+    const m = line.match(/^([A-Z0-9_]+)=(.*)$/);
+    if (!m) continue;
+    result[m[1]] = m[2];
+  }
+  return result;
+}
+
+function buildBlock(key, { account, apiKey, rotatedAt }) {
+  const prefix = `CONSTRUCT_CREDS_${key}`;
+  const lines = [blockStart(key)];
+  if (apiKey !== undefined) lines.push(`${prefix}_KEY=${apiKey}`);
+  if (account !== undefined) lines.push(`${prefix}_ACCOUNT=${account}`);
+  if (rotatedAt !== undefined) lines.push(`${prefix}_ROTATED_AT=${rotatedAt}`);
+  lines.push(blockEnd(key));
+  return lines.join('\n');
+}
+
+function nextRotationDue(rotatedAtStr) {
+  if (!rotatedAtStr) return null;
+  const d = new Date(rotatedAtStr);
+  if (isNaN(d.getTime())) return null;
+  d.setDate(d.getDate() + 90);
+  return d.toISOString().slice(0, 10);
+}
+
+export function readCreds() {
+  const raw = readRaw();
+  const blocks = extractBlocks(raw);
+  const result = {};
+
+  for (const [upperKey, blockText] of Object.entries(blocks)) {
+    const prefix = `CONSTRUCT_CREDS_${upperKey}`;
+    const fields = parseBlock(blockText);
+    const rotatedAt = fields[`${prefix}_ROTATED_AT`] || null;
+    result[upperKey.toLowerCase().replace(/_/g, '-')] = {
+      account: fields[`${prefix}_ACCOUNT`] || null,
+      key: fields[`${prefix}_KEY`] || null,
+      rotatedAt,
+      nextRotationDue: nextRotationDue(rotatedAt),
+    };
+  }
+
+  return result;
+}
+
+export function writeCreds(provider, { key, account } = {}) {
+  const pKey = providerKey(provider);
+  const raw = readRaw();
+  const blocks = extractBlocks(raw);
+
+  const existing = blocks[pKey] ? parseBlock(blocks[pKey]) : {};
+  const prefix = `CONSTRUCT_CREDS_${pKey}`;
+
+  const rotatedAt = key !== undefined
+    ? new Date().toISOString().slice(0, 10)
+    : (existing[`${prefix}_ROTATED_AT`] || null);
+
+  const mergedAccount = account !== undefined ? account : (existing[`${prefix}_ACCOUNT`] || undefined);
+  const mergedKey = key !== undefined ? key : (existing[`${prefix}_KEY`] || undefined);
+
+  const newBlock = buildBlock(pKey, { account: mergedAccount, apiKey: mergedKey, rotatedAt });
+
+  let newRaw;
+  if (blocks[pKey]) {
+    const startIdx = raw.indexOf(blockStart(pKey));
+    const endIdx = raw.indexOf(blockEnd(pKey)) + blockEnd(pKey).length;
+    newRaw = raw.slice(0, startIdx) + newBlock + raw.slice(endIdx);
+  } else {
+    const trimmed = raw.trimEnd();
+    newRaw = trimmed ? `${trimmed}\n\n${newBlock}\n` : `${newBlock}\n`;
+  }
+
+  writeRaw(newRaw);
+}
+
+export function deleteCreds(provider) {
+  const pKey = providerKey(provider);
+  const raw = readRaw();
+  const start = blockStart(pKey);
+  const end = blockEnd(pKey);
+
+  const startIdx = raw.indexOf(start);
+  if (startIdx === -1) return;
+
+  const endIdx = raw.indexOf(end, startIdx);
+  if (endIdx === -1) return;
+
+  const before = raw.slice(0, startIdx).trimEnd();
+  const after = raw.slice(endIdx + end.length).trimStart();
+
+  const newRaw = before && after
+    ? `${before}\n\n${after}`
+    : before
+      ? `${before}\n`
+      : after || '';
+
+  writeRaw(newRaw);
+}
+
+export function checkCredsFileMode() {
+  const fp = credsFilePath();
+  try {
+    const stat = fs.statSync(fp);
+    const mode = stat.mode & 0o777;
+    const modeStr = '0' + mode.toString(8);
+    return { ok: mode <= 0o600, mode: modeStr };
+  } catch (err) {
+    if (err.code === 'ENOENT') return { ok: true, mode: 'absent' };
+    throw err;
+  }
+}
+
+export function listCreds() {
+  const all = readCreds();
+  return Object.entries(all).map(([provider, data]) => ({
+    provider,
+    account: data.account,
+    rotatedAt: data.rotatedAt,
+    nextRotationDue: data.nextRotationDue,
+  }));
+}

package/lib/providers/scaffold.mjs

@@ -0,0 +1,107 @@
+/**
+ * lib/providers/scaffold.mjs — provider scaffold generator.
+ *
+ * Reads the template files from `templates/provider-scaffold/`, substitutes
+ * the %%PROVIDER_NAME%% and %%CAPABILITIES%% placeholders, and writes the
+ * result into `lib/providers/<name>/`. Returns the list of files created so
+ * the CLI can report them to the user.
+ *
+ * Supported capabilities: read, search, write, watch, webhook.
+ * The `read` and `search` methods are always included in the generated
+ * index.mjs; additional capabilities listed in `options.capabilities` add
+ * stub implementations for write, watch, and webhook.
+ *
+ * `scaffoldProvider` is idempotent with respect to the directory: it will
+ * not overwrite an existing file unless `options.force = true`. This prevents
+ * accidental loss of work when a developer reruns the command.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.resolve(__dirname, '..', '..', 'templates', 'provider-scaffold');
+
+const ALL_CAPABILITIES = ['read', 'search', 'write', 'watch', 'webhook'];
+
+function capabilityStub(cap) {
+  const stubs = {
+    write: `
+    async write(payload, config = {}) {
+      // Replace with a real write operation against the remote system. // construct-lint-ignore
+      throw new Error('not implemented');
+    },`,
+    watch: `
+    async watch(config = {}, callback) {
+      // Replace with a real subscription; call callback(item) on new events. // construct-lint-ignore
+      throw new Error('not implemented');
+    },`,
+    webhook: `
+    async webhook(config = {}, request) {
+      // Replace with real webhook signature verification and dispatch. // construct-lint-ignore
+      return { ok: false, error: 'not implemented' };
+    },`,
+  };
+  return stubs[cap] || '';
+}
+
+function renderIndex(name, capabilities) {
+  const capList = capabilities.filter((c) => ALL_CAPABILITIES.includes(c));
+  const capString = capList.join(', ');
+
+  const extraStubs = capList
+    .filter((c) => !['read', 'search'].includes(c))
+    .map(capabilityStub)
+    .join('\n');
+
+  const template = fs.readFileSync(path.join(TEMPLATES_DIR, 'index.mjs'), 'utf8');
+  let rendered = template
+    .replace(/%%PROVIDER_NAME%%/g, name)
+    .replace(/%%CAPABILITIES%%/g, capString);
+
+  if (extraStubs) {
+    rendered = rendered.replace(
+      /(\s+async search\(query, config = \{\}\) \{[\s\S]*?throw new Error\('not implemented'\);\n\s+\},)/,
+      `$1\n${extraStubs}`,
+    );
+  }
+
+  return rendered;
+}
+
+function renderTest(name) {
+  const template = fs.readFileSync(path.join(TEMPLATES_DIR, 'health.test.mjs'), 'utf8');
+  return template.replace(/%%PROVIDER_NAME%%/g, name);
+}
+
+export async function scaffoldProvider(name, options = {}) {
+  const {
+    capabilities = ['read', 'search'],
+    cwd = process.cwd(),
+    force = false,
+  } = options;
+
+  if (!name || typeof name !== 'string' || !/^[a-z0-9-]+$/.test(name)) {
+    throw new Error(`scaffoldProvider: name must be a lowercase alphanumeric-and-hyphen string, got '${name}'`);
+  }
+
+  const providerDir = path.join(cwd, 'lib', 'providers', name);
+  fs.mkdirSync(providerDir, { recursive: true });
+
+  const files = [];
+
+  const indexPath = path.join(providerDir, 'index.mjs');
+  if (force || !fs.existsSync(indexPath)) {
+    fs.writeFileSync(indexPath, renderIndex(name, capabilities), 'utf8');
+    files.push(indexPath);
+  }
+
+  const testPath = path.join(providerDir, 'health.test.mjs');
+  if (force || !fs.existsSync(testPath)) {
+    fs.writeFileSync(testPath, renderTest(name), 'utf8');
+    files.push(testPath);
+  }
+
+  return { providerDir, files };
+}

package/lib/role-preload.mjs

@@ -34,11 +34,16 @@ function stripTopHeading(body) {
 export function readRoleFile(root, name, opts = {}) {
   const p = path.join(root, "skills", "roles", `${name}.md`);
   if (!fs.existsSync(p)) return null;
+  const t0 = Date.now();
   const body = stripTopHeading(stripFrontmatter(fs.readFileSync(p, "utf8"))).trim();
   logSkillCall({
     skillId: `roles/${name}`,
     source: opts.source || 'role-preload',
     callerContext: opts.callerContext,
+    latencyMs: Date.now() - t0,
+    agentId: opts.agentId,
+    sessionId: opts.sessionId,
+    tokensReturned: Math.ceil(body.length / 4),
   });
   return body;
 }

package/lib/roles/catalog.mjs

@@ -1,7 +1,7 @@
 /**
  * lib/roles/catalog.mjs — role listing and display helpers.
  *
- * Reads agents/registry.json to produce a list of available roles with
+ * Reads specialists/registry.json to produce a list of available roles with
  * optional department grouping and consolidated-role views. Consumed by the
  * `roles:list` CLI command.
  */

package/lib/roles/manifest.mjs

@@ -1,7 +1,7 @@
 /**
  * lib/roles/manifest.mjs — role manifest loader.
  *
- * Reads agents/role-manifests.json. A persona is "onboarded" when its
+ * Reads specialists/role-manifests.json. A persona is "onboarded" when its
  * `events` array is non-empty. Empty entries reserve the slot for future
  * wiring without code change.
  */
@@ -11,7 +11,7 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const MANIFEST_PATH = join(__dirname, '..', '..', 'agents', 'role-manifests.json');
+const MANIFEST_PATH = join(__dirname, '..', '..', 'specialists', 'role-manifests.json');
 
 let cached = null;