draftgo-cli 3.0.55 → 4.0.1

package/src/commands/worklog.js

@@ -0,0 +1,86 @@
+'use strict';
+
+const log = require('../logger');
+const {
+  appendItem,
+  mutateWorklog,
+  normalizeDate,
+  readWorklog,
+  renderWorklog,
+  resolveReference,
+  updateItem,
+  worklogPath,
+} = require('../worklog');
+
+function printUsage() {
+  log.err('Usage: draftgo work start|add|start-item|complete|show|list <value>');
+}
+
+function output(flags, value) {
+  if (flags.output === 'json') console.log(JSON.stringify(value, null, 2));
+}
+
+function latestReference(blocks) {
+  const block = blocks[blocks.length - 1];
+  return `${block.date}#${block.entries[block.entries.length - 1].number}`;
+}
+
+function resultFor(blocks, reference) {
+  const resolved = resolveReference(blocks, reference);
+  return { date: resolved.block.date, ...resolved.entry };
+}
+
+function add(projectDir, positional, flags, status) {
+  const title = positional.join(' ').trim();
+  if (!title) { printUsage(); return 1; }
+  const result = mutateWorklog(projectDir, (blocks) => {
+    const date = normalizeDate(flags.date);
+    const next = appendItem(blocks, title, status, flags.note ? [String(flags.note).trim()] : [], date);
+    return { blocks: next, reference: latestReference(next) };
+  });
+  output(flags, { path: result.path, item: resultFor(result.blocks, result.reference) });
+  if (flags.output !== 'json') log.ok(`Worklog item added: ${title}`);
+  return 0;
+}
+
+function change(projectDir, positional, flags, status) {
+  const reference = positional[0];
+  if (!reference) { printUsage(); return 1; }
+  const result = mutateWorklog(projectDir, (blocks) => {
+    const note = flags.note == null ? '' : String(flags.note).trim();
+    const next = updateItem(blocks, reference, status, note);
+    return { blocks: next, reference };
+  });
+  output(flags, { path: result.path, item: resultFor(result.blocks, result.reference) });
+  if (flags.output !== 'json') log.ok(`Worklog item ${result.reference} marked ${status}.`);
+  return 0;
+}
+
+function show(projectDir, flags) {
+  const blocks = readWorklog(projectDir);
+  output(flags, { path: worklogPath(projectDir), blocks });
+  if (flags.output !== 'json') console.log(renderWorklog(blocks) || 'Worklog is empty.');
+  return 0;
+}
+
+function list(projectDir, flags) {
+  const blocks = readWorklog(projectDir);
+  const items = blocks.flatMap((block) => block.entries.map((entry) => ({ date: block.date, ...entry })));
+  output(flags, { path: worklogPath(projectDir), items });
+  if (flags.output !== 'json') items.forEach((item) => log.info(`${item.date}#${item.number} [${item.status}] ${item.title}`));
+  return 0;
+}
+
+async function worklog(projectDir, positional = [], flags = {}) {
+  const operation = positional[0] || 'show';
+  if (operation === 'start') return add(projectDir, positional.slice(1), flags, 'active');
+  if (operation === 'add') return add(projectDir, positional.slice(1), flags, 'pending');
+  if (operation === 'start-item' || operation === 'start_item') return change(projectDir, positional.slice(1), flags, 'active');
+  if (operation === 'complete' || operation === 'done') return change(projectDir, positional.slice(1), flags, 'completed');
+  if (operation === 'show') return show(projectDir, flags);
+  if (operation === 'list') return list(projectDir, flags);
+  throw new Error(`Unknown worklog operation ${operation}.`);
+}
+
+worklog.printUsage = printUsage;
+module.exports = worklog;

package/src/customServices.js

@@ -25,11 +25,12 @@ function loadManifest(projectDir) {
 }
 function atomicWrite(file, value) {
   fs.mkdirSync(path.dirname(file), { recursive: true });
-  const temporary = `${file}.tmp-${process.pid}-${Date.now()}`;
+  const temporary = `${file}.tmp-${process.pid}-${Date.now()}-${crypto.randomBytes(8).toString('hex')}`;
   fs.writeFileSync(temporary, value); fs.renameSync(temporary, file);
 }
 function saveManifest(projectDir, value) { value.updated_at = new Date().toISOString(); atomicWrite(manifestPath(projectDir), `${JSON.stringify(value, null, 2)}\n`); }
 function entryKey(id) { return String(id); }
+function uniqueIDs(ids) { return [...new Set(ids.map(String).map((id) => id.trim()).filter(Boolean))]; }
 function serviceDir(projectDir, id, slug) { return path.join(root(projectDir), `${safe(slug || id)}-${safe(id)}`); }
 function serviceBaseDir(projectDir, id) { return path.join(baseRoot(projectDir), safe(id)); }
 function parseEnvelope(text, response) {
@@ -95,6 +96,32 @@ function filesMatchRemote(files, remote) {
   const local = fileHashes(files); const expected = remoteFileHashes(remote);
   return FILES.every((filename) => expected[filename] && local[filename] === expected[filename]);
 }
+function canonicalFiles(files, remote) {
+  if (!remote || typeof remote.service_metadata_json !== 'string') {
+    throw new WorktreeError('INCOMPLETE_CHECKOUT_METADATA', 'DraftGo did not return canonical custom-service metadata.');
+  }
+  const canonical = { ...files, 'service.json': Buffer.from(remote.service_metadata_json, 'utf8') };
+  JSON.parse(canonical['service.json'].toString('utf8'));
+  const actual = fileHashes(canonical); const expected = remoteFileHashes(remote);
+  for (const filename of FILES) {
+    if (!/^[a-f0-9]{64}$/i.test(String(expected[filename] || '')) || actual[filename] !== expected[filename]) {
+      throw new WorktreeError('HASH_MISMATCH', `Canonical custom-service ${filename} does not match checkout metadata.`, {
+        filename, expected_hash: expected[filename] || null, actual_hash: actual[filename],
+      });
+    }
+  }
+  return canonical;
+}
+function applyRemoteEntry(entry, remote, files) {
+  const canonical = canonicalFiles(files, remote);
+  writeFiles(entry.local_dir, canonical); writeFiles(entry.base_dir, canonical);
+  entry.title = remote.title; entry.slug = JSON.parse(canonical['service.json'].toString('utf8')).slug;
+  entry.file_hashes = fileHashes(canonical); entry.base_hash = remote.content_hash;
+  entry.base_revision = remote.base_revision; entry.base_etag = remote.etag;
+  entry.checkout_source = remote.checkout_source; entry.updated_at = remote.updated_at;
+  entry.updated_by = remote.updated_by; entry.committed_at = new Date().toISOString();
+  return canonical;
+}
 function localState(entry) {
   const local = readFiles(entry.local_dir); const base = readFiles(entry.base_dir);
   const localHashes = fileHashes(local); const baseHashes = fileHashes(base);
@@ -103,8 +130,9 @@ function localState(entry) {
     modified: FILES.some((filename) => localHashes[filename] !== baseHashes[filename]) };
 }
 async function checkout(projectDir, ids, options = {}) {
-  const config = options.config || loadProjectConfig(projectDir); const manifest = loadManifest(projectDir); const results = [];
-  for (const id of ids) {
+  const config = options.config || loadProjectConfig(projectDir); const manifest = loadManifest(projectDir);
+  const targets = uniqueIDs(ids);
+  const settled = await Promise.allSettled(targets.map(async (id) => {
     const remote = await metadata(config, id, options); const key = entryKey(id); const old = manifest.entries[key];
     if (old && fs.existsSync(old.local_dir) && !options.force && localState(old).modified) {
       throw new WorktreeError('LOCAL_CHANGES_PRESENT', `Refusing to replace locally modified custom service ${id}; commit it or use checkout --force.`);
@@ -117,7 +145,20 @@ async function checkout(projectDir, ids, options = {}) {
       content_type: remote.content_type, base_revision: remote.base_revision, base_etag: remote.etag,
       base_hash: remote.content_hash, file_hashes: fileHashes(files), checkout_source: remote.checkout_source,
       checked_out_at: new Date().toISOString(), updated_at: remote.updated_at, updated_by: remote.updated_by };
-    manifest.entries[key] = entry; saveManifest(projectDir, manifest); results.push(entry);
+    return entry;
+  }));
+  const results = settled.filter((item) => item.status === 'fulfilled').map((item) => item.value);
+  for (const entry of results) manifest.entries[entryKey(entry.resource_id)] = entry;
+  if (results.length) saveManifest(projectDir, manifest);
+  const failures = settled.map((item, index) => ({ item, id: targets[index] })).filter(({ item }) => item.status === 'rejected');
+  if (failures.length) {
+    const error = failures[0].item.reason;
+    error.details = { ...(error.details || {}), batch: {
+      completed: results.map((entry) => ({ resource_id: entry.resource_id, status: 'checked_out' })),
+      failed: failures.map(({ item, id }) => ({ resource_id: id, status: 'failed', code: item.reason.code || 'CHECKOUT_FAILED', message: item.reason.message })),
+      not_started: [],
+    } };
+    throw error;
   }
   return results;
 }
@@ -163,23 +204,34 @@ function resolveConflict(projectDir, id) {
   atomicWrite(path.resolve(projectDir, record.manifest_path), `${JSON.stringify(resolved, null, 2)}\n`); return { ...resolved, manifest_path: record.manifest_path };
 }
 async function commit(projectDir, ids, options = {}) {
-  const config = options.config || loadProjectConfig(projectDir); const manifest = loadManifest(projectDir); const results = [];
-  const prepared = [];
-  for (const id of ids) {
+  const config = options.config || loadProjectConfig(projectDir); const manifest = loadManifest(projectDir);
+  const targets = uniqueIDs(ids);
+  const preflight = await Promise.allSettled(targets.map(async (id) => {
     const entry = manifest.entries[entryKey(id)]; if (!entry) throw new WorktreeError('RESOURCE_NOT_CHECKED_OUT', `Custom service ${id} is not checked out.`);
     if (entry.server !== config.server) throw new WorktreeError('CHECKOUT_SERVER_MISMATCH', 'Checkout belongs to a different DraftGo server.');
     const state = localState(entry); if (!state.base_valid) throw new WorktreeError('BASE_HASH_MISMATCH', `Custom service ${id} base does not match its manifest.`);
-    if (!state.modified) { prepared.push({ id, entry, state, unchanged: true }); continue; }
+    if (!state.modified) return { id, entry, state, unchanged: true };
     const current = await metadata(config, id, options);
     if (current.content_hash !== entry.base_hash || String(current.base_revision) !== String(entry.base_revision)) {
       const remoteArchive = await download(config, current, options); const conflict = await writeConflict(projectDir, entry, current, remoteArchive);
       throw new WorktreeError('RESOURCE_VERSION_CONFLICT', `Custom service ${id} changed remotely; conflict materials were preserved.`, conflict);
     }
-    prepared.push({ id, entry, state, current, archive: createArchive(state.local) });
+    return { id, entry, state, current, archive: createArchive(state.local) };
+  }));
+  const preflightFailures = preflight.map((item, index) => ({ item, id: targets[index] })).filter(({ item }) => item.status === 'rejected');
+  if (preflightFailures.length) {
+    const error = preflightFailures[0].item.reason;
+    error.details = { ...(error.details || {}), batch: {
+      completed: [],
+      failed: preflightFailures.map(({ item, id }) => ({ resource_id: id, status: 'failed', phase: 'preflight', code: item.reason.code || 'PREFLIGHT_FAILED', message: item.reason.message })),
+      not_started: preflight.filter((item) => item.status === 'fulfilled').map((item) => ({ resource_id: item.value.id, status: 'not_started', phase: 'preflight' })),
+    } };
+    throw error;
   }
-  for (const item of prepared) {
-    const { id, entry, current, archive } = item;
-    if (item.unchanged) { results.push({ resource_type: 'custom_services', resource_id: String(id), status: 'unchanged' }); continue; }
+  const prepared = preflight.map((item) => item.value);
+  const uploaded = await Promise.allSettled(prepared.map(async (item) => {
+    const { id, entry, current, archive, state } = item;
+    if (item.unchanged) return { resource_type: 'custom_services', resource_id: String(id), status: 'unchanged' };
     const url = new URL(current.commit_url, `${config.server.replace(/\/+$/, '')}/`).toString();
     const response = await (options.fetch || fetch)(url, { method: 'PUT', headers: { Authorization: `Bearer ${config.token || config.sat}`, 'Content-Type': current.content_type,
       'Content-Length': String(archive.length), 'X-Content-SHA256': sha256(archive), 'If-Match': entry.base_etag }, body: archive, signal: options.signal });
@@ -188,12 +240,20 @@ async function commit(projectDir, ids, options = {}) {
       if ([409, 412].includes(error.status)) { const latest = await metadata(config, id, options); const remoteArchive = await download(config, latest, options); error.details = await writeConflict(projectDir, entry, latest, remoteArchive); }
       throw error;
     }
-    const canonicalArchive = await download(config, committed, options); const canonicalFiles = archiveFiles(canonicalArchive);
-    writeFiles(entry.local_dir, canonicalFiles); writeFiles(entry.base_dir, canonicalFiles);
-    entry.file_hashes = fileHashes(canonicalFiles); entry.base_hash = committed.content_hash;
-    entry.base_revision = committed.base_revision; entry.base_etag = committed.etag; entry.updated_at = committed.updated_at; entry.updated_by = committed.updated_by; entry.committed_at = new Date().toISOString();
-    manifest.entries[entryKey(id)] = entry; saveManifest(projectDir, manifest);
-    results.push({ resource_type: 'custom_services', resource_id: String(id), status: 'committed', revision: committed.base_revision, hash: committed.content_hash });
+    applyRemoteEntry(entry, committed, state.local); manifest.entries[entryKey(id)] = entry;
+    return { resource_type: 'custom_services', resource_id: String(id), status: 'committed', revision: committed.base_revision, hash: committed.content_hash };
+  }));
+  const results = uploaded.filter((item) => item.status === 'fulfilled').map((item) => item.value);
+  if (results.some((item) => item.status === 'committed')) saveManifest(projectDir, manifest);
+  const uploadFailures = uploaded.map((item, index) => ({ item, id: prepared[index].id })).filter(({ item }) => item.status === 'rejected');
+  if (uploadFailures.length) {
+    const error = uploadFailures[0].item.reason;
+    error.details = { ...(error.details || {}), batch: {
+      completed: results,
+      failed: uploadFailures.map(({ item, id }) => ({ resource_id: id, status: 'failed', phase: 'upload', code: item.reason.code || 'COMMIT_FAILED', message: item.reason.message, remote_change_possible: true })),
+      not_started: [],
+    } };
+    throw error;
   }
   return results;
 }
@@ -202,22 +262,48 @@ async function inspectRemote(projectDir, options = {}) {
   const requested = options.ids ? new Set(options.ids.map(String)) : null;
   const entries = Object.values(loadManifest(projectDir).entries)
     .filter((entry) => !requested || requested.has(String(entry.resource_id)));
-  const result = [];
-  for (const entry of entries) {
+  return Promise.all(entries.map(async (entry) => {
     const state = localState(entry); const remote = await metadata(config, entry.resource_id, options); const remoteMatches = remote.content_hash === entry.base_hash && String(remote.base_revision) === String(entry.base_revision);
     const localArchiveHash = checkoutHash(state.local); let status;
     if (remoteMatches) status = state.modified ? 'local_modified' : 'clean';
     else if (!state.modified) status = 'remote_changed';
     else if (filesMatchRemote(state.local, remote)) status = 'committed_unrecorded';
     else status = 'diverged';
-    result.push({ ...entry, state: status, remote_hash: remote.content_hash, remote_revision: remote.base_revision, remote_etag: remote.etag, local_hash: localArchiveHash });
-  }
+    return { ...entry, state: status, remote_hash: remote.content_hash, remote_revision: remote.base_revision, remote_etag: remote.etag, local_hash: localArchiveHash };
+  }));
+}
+function currentServiceMetadata(entry) { return JSON.parse(readFiles(entry.local_dir)['service.json'].toString('utf8')); }
+function validationCurrent(entry) {
+  const value = currentServiceMetadata(entry);
+  return value.validation_status === 'passed' && String(value.validated_revision) === String(entry.base_revision)
+    && /^[a-f0-9]{64}$/i.test(String(value.validated_hash || ''));
+}
+function syncCheckoutEntry(manifest, id, remote) {
+  const entry = manifest.entries[entryKey(id)];
+  if (!entry) throw new WorktreeError('RESOURCE_NOT_CHECKED_OUT', `Custom service ${id} is not checked out.`);
+  const state = localState(entry);
+  if (state.modified) throw new WorktreeError('LOCAL_CHANGES_PRESENT', `Custom service ${id} changed locally during its remote lifecycle.`);
+  applyRemoteEntry(entry, remote, state.local); manifest.entries[entryKey(id)] = entry;
+  return entry;
+}
+async function validateCommitted(projectDir, id, config, manifest, options = {}) {
+  const entry = manifest.entries[entryKey(id)];
+  if (!entry) throw new WorktreeError('RESOURCE_NOT_CHECKED_OUT', `Custom service ${id} is not checked out.`);
+  if (validationCurrent(entry)) return { validation_status: 'passed', revision: entry.base_revision, checkout: null, cached: true };
+  const result = await jsonRequest(config, 'POST', `scripts/${encodeURIComponent(id)}/draft/validate`, { revision: entry.base_revision }, options);
+  if (!result.checkout) throw new WorktreeError('INCOMPLETE_CHECKOUT_METADATA', 'DraftGo validation response did not include checkout metadata.');
+  syncCheckoutEntry(manifest, id, result.checkout);
   return result;
 }
+function validationStale(error) {
+  return Boolean(error) && error.status === 409 && error.code === 'VALIDATION_FAILED'
+    && error.details && error.details.reason === 'validation_stale';
+}
 async function validate(projectDir, id, options = {}) {
-  const config = options.config || loadProjectConfig(projectDir); await commit(projectDir, [id], options);
-  const result = await jsonRequest(config, 'POST', `scripts/${encodeURIComponent(id)}/draft/validate`, {}, options);
-  await checkout(projectDir, [id], { ...options, config, force: true }); return result;
+  const config = options.config || loadProjectConfig(projectDir); await commit(projectDir, [id], { ...options, config });
+  const manifest = loadManifest(projectDir); const result = await validateCommitted(projectDir, id, config, manifest, options);
+  if (!result.cached) saveManifest(projectDir, manifest);
+  return result;
 }
 function parseHandler(handler) {
   const value = String(handler || '').trim(); if (!value) return undefined;
@@ -228,19 +314,50 @@ function parseHandler(handler) {
   return { kind: 'manual', name: value };
 }
 async function test(projectDir, id, input = {}, options = {}) {
-  const config = options.config || loadProjectConfig(projectDir); await validate(projectDir, id, options);
-  return jsonRequest(config, 'POST', `scripts/${encodeURIComponent(id)}/draft/execute`, {
+  const config = options.config || loadProjectConfig(projectDir); await commit(projectDir, [id], { ...options, config });
+  const manifest = loadManifest(projectDir); const validation = await validateCommitted(projectDir, id, config, manifest, options);
+  const entry = manifest.entries[entryKey(id)];
+  if (!validation.cached) saveManifest(projectDir, manifest);
+  const result = await jsonRequest(config, 'POST', `scripts/${encodeURIComponent(id)}/draft/execute`, {
     input, selector: parseHandler(options.handler), headers: options.headers, user: options.user,
-    test_write: Boolean(options.testWrite), side_effect_policy: options.sideEffectPolicy || 'deny',
+    test_write: Boolean(options.testWrite), side_effect_policy: options.sideEffectPolicy || 'deny', revision: entry.base_revision,
   }, options);
+  if (result.checkout) { syncCheckoutEntry(manifest, id, result.checkout); saveManifest(projectDir, manifest); }
+  return result;
 }
 async function publish(projectDir, ids, options = {}) {
-  const config = options.config || loadProjectConfig(projectDir); const results = [];
-  for (const id of ids) {
-    await validate(projectDir, id, options); results.push(await jsonRequest(config, 'POST', `scripts/${encodeURIComponent(id)}/draft/publish`, {}, options));
-    await checkout(projectDir, [id], { ...options, config, force: true });
+  const config = options.config || loadProjectConfig(projectDir); const targets = uniqueIDs(ids);
+  await commit(projectDir, targets, { ...options, config });
+  const manifest = loadManifest(projectDir);
+  const validations = await Promise.all(targets.map((id) => validateCommitted(projectDir, id, config, manifest, options)));
+  if (validations.some((result) => !result.cached)) saveManifest(projectDir, manifest);
+  const published = await Promise.allSettled(targets.map(async (id) => {
+    let entry = manifest.entries[entryKey(id)];
+    const requestPublish = () => jsonRequest(config, 'POST', `scripts/${encodeURIComponent(id)}/draft/publish`, { revision: entry.base_revision }, options);
+    let result;
+    try {
+      result = await requestPublish();
+    } catch (error) {
+      if (!validationStale(error)) throw error;
+      const validation = await jsonRequest(config, 'POST', `scripts/${encodeURIComponent(id)}/draft/validate`, { revision: entry.base_revision }, options);
+      if (!validation.checkout) throw new WorktreeError('INCOMPLETE_CHECKOUT_METADATA', 'DraftGo validation response did not include checkout metadata.');
+      entry = syncCheckoutEntry(manifest, id, validation.checkout);
+      result = await requestPublish();
+    }
+    if (!result.checkout) throw new WorktreeError('INCOMPLETE_CHECKOUT_METADATA', 'DraftGo publish response did not include checkout metadata.');
+    syncCheckoutEntry(manifest, id, result.checkout); return result;
+  }));
+  const results = published.filter((item) => item.status === 'fulfilled').map((item) => item.value);
+  if (results.length) saveManifest(projectDir, manifest);
+  const failures = published.map((item, index) => ({ item, id: targets[index] })).filter(({ item }) => item.status === 'rejected');
+  if (failures.length) {
+    const error = failures[0].item.reason;
+    error.details = { ...(error.details || {}), batch: {
+      completed: results, failed: failures.map(({ item, id }) => ({ resource_id: id, status: 'failed', code: item.reason.code || 'PUBLISH_FAILED', message: item.reason.message })), not_started: [],
+    } };
+    throw error;
   }
   return results;
 }
 
-module.exports = { FILES, checkout, commit, diff, validate, test, publish, inspectRemote, loadManifest, getEntry, metadata, archiveFiles, createArchive, serviceConflicts, showConflict, resolveConflict, parseHandler };
+module.exports = { FILES, checkout, commit, diff, validate, test, publish, inspectRemote, loadManifest, getEntry, metadata, archiveFiles, createArchive, serviceConflicts, showConflict, resolveConflict, parseHandler, validationStale };

package/src/{localdev → localRuntime}/detect.js

@@ -1,6 +1,6 @@
 'use strict';
 
-// Environment detection helpers for the local-dev wizard.
+// Environment detection helpers for the local stack setup wizard.
 //   - probePort:      TCP probe (used to find existing MySQL/Redis)
 //   - probeHttp:      HTTP GET probe with retry (used to wait for the app)
 //   - detectDocker:   Find a working `docker` + `docker compose` (or `docker-compose`)

package/src/{localdev → localRuntime}/mysqlClient.js

@@ -1,6 +1,6 @@
 'use strict';
 
-// Lightweight MySQL helper used by the local-dev wizard to validate
+// Lightweight MySQL helper used by the local stack wizard to validate
 // credentials and auto-create the project database when missing.
 //
 // We avoid taking a JS MySQL driver as a dependency. Instead we shell out

package/src/{localdev → localRuntime}/services.js

@@ -1,6 +1,6 @@
 'use strict';
 
-// Shared local dependencies live outside individual projects. Project Compose
+// Shared local runtime dependencies live outside individual projects. Project Compose
 // files only start DraftGo itself and connect back to these loopback services.
 const net = require('net');
 const os = require('os');

package/src/projectConfig.js

@@ -9,6 +9,8 @@ const IGNORE_ENTRIES = [
   '.draftgo/token',
   '.draftgo/worktree/',
   '.draftgo/conflicts/',
+	'.draftgo/api-contract-cache.json',
+	'.draftgo/api-contract-cache.json.lock',
 ];
 
 function parseHttpUrl(raw) {

package/src/{installers/index.js → targets.js}

@@ -1,11 +1,9 @@
 'use strict';
 
-// Thin compatibility layer over src/platforms.js + src/skill.js.
-// Each "installer" is just a platform descriptor exposing install/uninstall/
-// status methods that delegate to the generic renderer.
+// Public Skill target registry backed by shared platform descriptors.
 
-const { platforms } = require('../platforms');
-const skill = require('../skill');
+const { platforms } = require('./platforms');
+const skill = require('./skill');
 
 function makeInstaller(p) {
   return {