@hasna/instructions 0.4.20 → 0.4.21

package/dist/mcp/index.js

@@ -586,6 +586,133 @@ var init_machine = __esm(() => {
   init_template();
 });
 
+// src/lib/compact-output.ts
+function parseLimit(value, fallback = DEFAULT_LIST_LIMIT, max = MAX_LIST_LIMIT) {
+  const parsed = typeof value === "number" ? value : Number.parseInt(String(value ?? ""), 10);
+  if (!Number.isFinite(parsed) || parsed <= 0)
+    return fallback;
+  return Math.min(Math.floor(parsed), max);
+}
+function parseCursor(value) {
+  const parsed = typeof value === "number" ? value : Number.parseInt(String(value ?? ""), 10);
+  if (!Number.isFinite(parsed) || parsed < 0)
+    return 0;
+  return Math.floor(parsed);
+}
+function paginate(items, opts = {}) {
+  const limit = parseLimit(opts.limit, opts.defaultLimit ?? DEFAULT_LIST_LIMIT, opts.maxLimit ?? MAX_LIST_LIMIT);
+  const cursor = parseCursor(opts.cursor);
+  const pageItems = items.slice(cursor, cursor + limit);
+  const nextCursor = cursor + pageItems.length < items.length ? cursor + pageItems.length : null;
+  return {
+    items: pageItems,
+    total: items.length,
+    limit,
+    cursor,
+    next_cursor: nextCursor,
+    has_more: nextCursor !== null
+  };
+}
+function pagedPayload(items, opts = {}) {
+  return {
+    ...paginate(items, opts),
+    hint: opts.hint
+  };
+}
+function truncateText(value, max = 80) {
+  const text = (value ?? "").replace(/\s+/g, " ").trim();
+  if (text.length <= max)
+    return text;
+  if (max <= 3)
+    return text.slice(0, max);
+  return `${text.slice(0, max - 3)}...`;
+}
+function summarizeConfig(config, opts = {}) {
+  const summary = {
+    id: config.id,
+    slug: config.slug,
+    name: config.name,
+    category: config.category,
+    agent: config.agent,
+    kind: config.kind,
+    format: config.format,
+    target_path: config.target_path,
+    output_count: config.outputs.length,
+    version: config.version,
+    is_template: config.is_template
+  };
+  if (opts.verbose) {
+    summary.updated_at = config.updated_at;
+    summary.description = config.description;
+    summary.tags = config.tags;
+    summary.outputs = config.outputs;
+  }
+  return summary;
+}
+function summarizeProfile(profile, opts = {}) {
+  const selectorCount = (profile.selectors.os?.length ?? 0) + (profile.selectors.arch?.length ?? 0) + (profile.selectors.hostnames?.length ?? 0);
+  const summary = {
+    id: profile.id,
+    slug: profile.slug,
+    name: profile.name,
+    description: opts.verbose ? profile.description : truncateText(profile.description, 80),
+    selector_count: selectorCount,
+    variable_count: Object.keys(profile.variables).length
+  };
+  if (opts.verbose) {
+    summary.created_at = profile.created_at;
+    summary.updated_at = profile.updated_at;
+    summary.selectors = profile.selectors;
+    summary.variables = profile.variables;
+  }
+  return summary;
+}
+function summarizeApplyResult(result) {
+  return {
+    config_id: result.config_id,
+    path: result.path,
+    dry_run: result.dry_run,
+    changed: result.changed,
+    primary_changed: result.primary_changed,
+    agent: result.agent,
+    transform: result.transform,
+    output_count: result.outputs?.length ?? 0,
+    outputs: result.outputs?.map(summarizeApplyResult)
+  };
+}
+var DEFAULT_LIST_LIMIT = 20, MAX_LIST_LIMIT = 100;
+
+// src/lib/bounded-read.ts
+function normalizeBoundedReadOptions(options = {}) {
+  return {
+    limit: parseLimit(options.limit, DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT),
+    cursor: parseCursor(options.cursor)
+  };
+}
+function boundedReadPage(items, total, options = {}) {
+  const { limit, cursor } = normalizeBoundedReadOptions(options);
+  if (items.length > limit) {
+    throw new Error(`bounded read returned ${items.length} rows for limit ${limit}`);
+  }
+  const consumed = cursor + items.length;
+  const complete = consumed >= total;
+  if (!complete && items.length === 0) {
+    throw new Error(`bounded read did not advance at cursor ${cursor} of ${total}`);
+  }
+  return {
+    items,
+    total,
+    limit,
+    cursor,
+    next_cursor: complete ? null : consumed,
+    has_more: !complete,
+    complete,
+    truncated: false,
+    source_bounded: true
+  };
+}
+var init_bounded_read = () => {};
+
 // src/db/profiles.ts
 function rowToProfile(row) {
   return {
@@ -629,9 +756,12 @@ function getProfile(idOrSlug, db) {
     throw new ProfileNotFoundError(idOrSlug);
   return rowToProfile(row);
 }
-function listProfiles(db) {
+function listProfilesPage(options = {}, db) {
   const d = db || getDatabase();
-  return d.query("SELECT * FROM profiles ORDER BY name").all().map(rowToProfile);
+  const normalized = normalizeBoundedReadOptions(options);
+  const total = d.query("SELECT COUNT(*) AS total FROM profiles").get()?.total ?? 0;
+  const rows = d.query("SELECT * FROM profiles ORDER BY name LIMIT ? OFFSET ?").all(normalized.limit, normalized.cursor).map(rowToProfile);
+  return boundedReadPage(rows, total, normalized);
 }
 function updateProfile(idOrSlug, input, db) {
   const d = db || getDatabase();
@@ -676,14 +806,13 @@ function removeConfigFromProfile(profileIdOrSlug, configId, db) {
   const profile = getProfile(profileIdOrSlug, d);
   d.run("DELETE FROM profile_configs WHERE profile_id = ? AND config_id = ?", [profile.id, configId]);
 }
-function getProfileConfigs(profileIdOrSlug, db) {
+function getProfileConfigsPage(profileIdOrSlug, options = {}, db) {
   const d = db || getDatabase();
   const profile = getProfile(profileIdOrSlug, d);
-  const rows = d.query("SELECT config_id FROM profile_configs WHERE profile_id = ? ORDER BY sort_order").all(profile.id);
-  if (rows.length === 0)
-    return [];
-  const ids = rows.map((r) => r.config_id);
-  return listConfigs(undefined, d).filter((c) => ids.includes(c.id));
+  const normalized = normalizeBoundedReadOptions(options);
+  const total = d.query("SELECT COUNT(*) AS total FROM profile_configs WHERE profile_id = ?").get(profile.id)?.total ?? 0;
+  const rows = d.query("SELECT config_id FROM profile_configs WHERE profile_id = ? ORDER BY sort_order LIMIT ? OFFSET ?").all(profile.id, normalized.limit, normalized.cursor);
+  return boundedReadPage(rows.map((row) => getConfigById(row.config_id, d)), total, normalized);
 }
 function profileHasSelectors(profile) {
   const selectors = profile.selectors ?? {};
@@ -699,20 +828,46 @@ function profileMatchesMachine(profile, machine) {
   const hostnameMatches = !selectors.hostnames?.length || selectors.hostnames.some((candidate) => candidate.trim().toLowerCase() === machine.hostname.trim().toLowerCase());
   return osMatches && archMatches && hostnameMatches;
 }
-function resolveProfileForMachine(machine = detectMachineContext(), db) {
-  const profiles = listProfiles(db).filter(profileHasSelectors);
-  const matches = profiles.filter((profile) => profileMatchesMachine(profile, machine)).map((profile) => {
-    const selectors = profile.selectors;
-    const score = (selectors.hostnames?.length ? 100 : 0) + (selectors.os?.length ? 10 : 0) + (selectors.arch?.length ? 10 : 0);
-    return { profile, score };
-  }).sort((a, b) => b.score - a.score || a.profile.name.localeCompare(b.profile.name));
-  return matches[0]?.profile ?? null;
+function resolveProfileForMachineRead(machine = detectMachineContext(), options = {}, db) {
+  const d = db || getDatabase();
+  const { limit } = normalizeBoundedReadOptions(options);
+  let cursor = 0;
+  let scanned = 0;
+  let total = 0;
+  let selected = null;
+  while (true) {
+    const page = listProfilesPage({ limit, cursor }, d);
+    total = page.total;
+    scanned += page.items.length;
+    for (const profile of page.items) {
+      if (!profileHasSelectors(profile) || !profileMatchesMachine(profile, machine))
+        continue;
+      const selectors = profile.selectors;
+      const score = (selectors.hostnames?.length ? 100 : 0) + (selectors.os?.length ? 10 : 0) + (selectors.arch?.length ? 10 : 0);
+      if (!selected || score > selected.score || score === selected.score && profile.name.localeCompare(selected.profile.name) < 0) {
+        selected = { profile, score };
+      }
+    }
+    if (page.complete)
+      break;
+    cursor = page.next_cursor;
+  }
+  return {
+    profile: selected?.profile ?? null,
+    scanned,
+    total,
+    batch_limit: limit,
+    source_bounded: true,
+    complete: true,
+    truncated: false
+  };
 }
 var init_profiles = __esm(() => {
   init_types();
   init_database();
   init_configs();
   init_machine();
+  init_bounded_read();
 });
 
 // src/db/snapshots.ts
@@ -790,6 +945,32 @@ var init_machines = __esm(() => {
 
 // src/data/config-store.ts
 import { randomUUID as randomUUID2 } from "crypto";
+function parseBoundedPagePayload(value, label) {
+  const page = value;
+  const consumed = Number(page?.cursor) + (page?.items?.length ?? 0);
+  const complete = Boolean(page && Number.isSafeInteger(page.total) && consumed >= Number(page.total));
+  if (!page || !Array.isArray(page.items) || !Number.isSafeInteger(page.total) || Number(page.total) < 0 || !Number.isSafeInteger(page.limit) || Number(page.limit) < 1 || !Number.isSafeInteger(page.cursor) || Number(page.cursor) < 0 || page.items.length > Number(page.limit) || typeof page.has_more !== "boolean" || typeof page.complete !== "boolean" || page.truncated !== false || page.next_cursor !== null && !Number.isSafeInteger(page.next_cursor) || page.complete !== complete || page.has_more !== !complete || page.next_cursor !== (complete ? null : consumed)) {
+    throw new CloudHttpError(502, `${label} returned an invalid or truncated bounded-read envelope`, value);
+  }
+  return {
+    ...page,
+    source_bounded: page.source_bounded ?? true
+  };
+}
+function parseBoundedOrLegacyPage(value, legacyItems, options, label) {
+  if (value && typeof value === "object") {
+    const candidate = value;
+    if ("items" in candidate || "total" in candidate || "complete" in candidate || "truncated" in candidate || "next_cursor" in candidate) {
+      return parseBoundedPagePayload(value, label);
+    }
+  }
+  if (!Array.isArray(legacyItems)) {
+    throw new CloudHttpError(502, `${label} returned neither a bounded envelope nor a complete legacy array`, value);
+  }
+  const normalized = normalizeBoundedReadOptions(options);
+  const page = boundedReadPage(legacyItems.slice(normalized.cursor, normalized.cursor + normalized.limit), legacyItems.length, normalized);
+  return { ...page, source_bounded: false };
+}
 function resolveCloudConfig(env = process.env) {
   const apiUrl = env[API_URL_ENV]?.trim();
   const apiKey = env[API_KEY_ENV]?.trim();
@@ -844,13 +1025,35 @@ class LocalConfigStore {
     return pruneSnapshots(configId, keep, this.db);
   }
   async listProfiles() {
-    return listProfiles(this.db);
+    const profiles = [];
+    let cursor = 0;
+    while (true) {
+      const page = await this.listProfilesPage({ limit: 100, cursor });
+      profiles.push(...page.items);
+      if (page.complete)
+        return profiles;
+      cursor = page.next_cursor;
+    }
+  }
+  async listProfilesPage(options = {}) {
+    return listProfilesPage(options, this.db);
   }
   async getProfile(idOrSlug) {
     return getProfile(idOrSlug, this.db);
   }
   async getProfileConfigs(idOrSlug) {
-    return getProfileConfigs(idOrSlug, this.db);
+    const configs = [];
+    let cursor = 0;
+    while (true) {
+      const page = await this.getProfileConfigsPage(idOrSlug, { limit: 100, cursor });
+      configs.push(...page.items);
+      if (page.complete)
+        return configs;
+      cursor = page.next_cursor;
+    }
+  }
+  async getProfileConfigsPage(idOrSlug, options = {}) {
+    return getProfileConfigsPage(idOrSlug, options, this.db);
   }
   async createProfile(input) {
     return createProfile(input, this.db);
@@ -868,7 +1071,10 @@ class LocalConfigStore {
     removeConfigFromProfile(profileIdOrSlug, configId, this.db);
   }
   async resolveProfileForMachine(machine) {
-    return machine ? resolveProfileForMachine(machine, this.db) : resolveProfileForMachine(undefined, this.db);
+    return (await this.resolveProfileForMachineRead(machine)).profile;
+  }
+  async resolveProfileForMachineRead(machine, options = {}) {
+    return machine ? resolveProfileForMachineRead(machine, options, this.db) : resolveProfileForMachineRead(undefined, options, this.db);
   }
   async registerMachine(hostname2, os, arch2) {
     return registerMachine(hostname2, os, arch2, this.db);
@@ -1009,8 +1215,24 @@ class CloudConfigStore {
     return data?.pruned ?? 0;
   }
   async listProfiles() {
-    const { data } = await this.request("GET", "/profiles");
-    return data?.profiles ?? [];
+    const profiles = [];
+    let cursor = 0;
+    while (true) {
+      const page = await this.listProfilesPage({ limit: 100, cursor });
+      profiles.push(...page.items);
+      if (page.complete)
+        return profiles;
+      cursor = page.next_cursor;
+    }
+  }
+  async listProfilesPage(options = {}) {
+    const normalized = normalizeBoundedReadOptions(options);
+    const params = new URLSearchParams;
+    params.set("limit", String(normalized.limit));
+    params.set("cursor", String(normalized.cursor));
+    const qs = params.toString();
+    const { data } = await this.request("GET", `/profiles${qs ? `?${qs}` : ""}`);
+    return parseBoundedOrLegacyPage(data, data?.profiles, normalized, "profile list");
   }
   async getProfile(idOrSlug) {
     const { status, data } = await this.request("GET", `/profiles/${encodeURIComponent(idOrSlug)}`, undefined, { allow404: true });
@@ -1020,10 +1242,26 @@ class CloudConfigStore {
     return profile;
   }
   async getProfileConfigs(idOrSlug) {
-    const { status, data } = await this.request("GET", `/profiles/${encodeURIComponent(idOrSlug)}`, undefined, { allow404: true });
+    const configs = [];
+    let cursor = 0;
+    while (true) {
+      const page = await this.getProfileConfigsPage(idOrSlug, { limit: 100, cursor });
+      configs.push(...page.items);
+      if (page.complete)
+        return configs;
+      cursor = page.next_cursor;
+    }
+  }
+  async getProfileConfigsPage(idOrSlug, options = {}) {
+    const normalized = normalizeBoundedReadOptions(options);
+    const params = new URLSearchParams;
+    params.set("limit", String(normalized.limit));
+    params.set("cursor", String(normalized.cursor));
+    const qs = params.toString();
+    const { status, data } = await this.request("GET", `/profiles/${encodeURIComponent(idOrSlug)}${qs ? `?${qs}` : ""}`, undefined, { allow404: true });
     if (status === 404 || !data?.profile)
       throw new ProfileNotFoundError(idOrSlug);
-    return data.profile.configs ?? [];
+    return parseBoundedOrLegacyPage(data.configs, data.profile.configs, normalized, "profile membership");
   }
   async createProfile(input) {
     const { data } = await this.request("POST", "/profiles", input, {
@@ -1047,6 +1285,10 @@ class CloudConfigStore {
     await this.request("DELETE", `/profiles/${encodeURIComponent(profileIdOrSlug)}/configs/${encodeURIComponent(configId)}`, undefined, { allow404: true });
   }
   async resolveProfileForMachine(machine) {
+    return (await this.resolveProfileForMachineRead(machine)).profile;
+  }
+  async resolveProfileForMachineRead(machine, options = {}) {
+    const normalized = normalizeBoundedReadOptions(options);
     const params = new URLSearchParams;
     if (machine?.hostname)
       params.set("hostname", machine.hostname);
@@ -1054,11 +1296,40 @@ class CloudConfigStore {
       params.set("os", machine.os);
     if (machine?.arch)
       params.set("arch", machine.arch);
+    params.set("limit", String(normalized.limit));
     const qs = params.toString();
     const { status, data } = await this.request("GET", `/profiles/resolve${qs ? `?${qs}` : ""}`, undefined, { allow404: true });
-    if (status === 404 || !data?.profile)
-      return null;
-    return data.profile;
+    if (status === 404) {
+      return {
+        profile: null,
+        scanned: null,
+        total: null,
+        batch_limit: null,
+        source_bounded: false,
+        complete: true,
+        truncated: false
+      };
+    }
+    if (data && "complete" in data) {
+      if (data.complete !== true || data.truncated !== false) {
+        throw new CloudHttpError(502, "profile resolve returned an incomplete or truncated read", data);
+      }
+      return { ...data, source_bounded: data.source_bounded ?? true };
+    }
+    if (data && "profile" in data) {
+      return {
+        profile: data.profile,
+        scanned: null,
+        total: null,
+        batch_limit: null,
+        source_bounded: false,
+        complete: true,
+        truncated: false
+      };
+    }
+    {
+      throw new CloudHttpError(502, "profile resolve returned an incomplete or truncated read", data);
+    }
   }
   async registerMachine(hostname2, os, arch2) {
     const { data } = await this.request("POST", "/machines", { hostname: hostname2, os, arch: arch2 }, { idempotent: true });
@@ -1095,6 +1366,7 @@ var init_config_store = __esm(() => {
   init_machines();
   init_database();
   init_types();
+  init_bounded_read();
   CloudHttpError = class CloudHttpError extends Error {
     status;
     body;
@@ -6957,7 +7229,7 @@ var init_sync_dir = __esm(() => {
 var require_package = __commonJS((exports, module) => {
   module.exports = {
     name: "@hasna/instructions",
-    version: "0.4.20",
+    version: "0.4.21",
     description: "AI coding agent instruction & configuration manager \u2014 store, version, apply, and share all your AI coding configs. CLI + MCP + HTTP API (instructions-serve) + generated SDK + Dashboard.",
     type: "module",
     main: "dist/index.js",
@@ -7081,105 +7353,6 @@ function findReferenceConfigsByName(configs, name) {
 // src/mcp/server.ts
 init_sync_dir();
 init_machine();
-
-// src/lib/compact-output.ts
-var DEFAULT_LIST_LIMIT = 20;
-var MAX_LIST_LIMIT = 100;
-function parseLimit(value, fallback = DEFAULT_LIST_LIMIT, max = MAX_LIST_LIMIT) {
-  const parsed = typeof value === "number" ? value : Number.parseInt(String(value ?? ""), 10);
-  if (!Number.isFinite(parsed) || parsed <= 0)
-    return fallback;
-  return Math.min(Math.floor(parsed), max);
-}
-function parseCursor(value) {
-  const parsed = typeof value === "number" ? value : Number.parseInt(String(value ?? ""), 10);
-  if (!Number.isFinite(parsed) || parsed < 0)
-    return 0;
-  return Math.floor(parsed);
-}
-function paginate(items, opts = {}) {
-  const limit = parseLimit(opts.limit, opts.defaultLimit ?? DEFAULT_LIST_LIMIT, opts.maxLimit ?? MAX_LIST_LIMIT);
-  const cursor = parseCursor(opts.cursor);
-  const pageItems = items.slice(cursor, cursor + limit);
-  const nextCursor = cursor + pageItems.length < items.length ? cursor + pageItems.length : null;
-  return {
-    items: pageItems,
-    total: items.length,
-    limit,
-    cursor,
-    next_cursor: nextCursor,
-    has_more: nextCursor !== null
-  };
-}
-function pagedPayload(items, opts = {}) {
-  return {
-    ...paginate(items, opts),
-    hint: opts.hint
-  };
-}
-function truncateText(value, max = 80) {
-  const text = (value ?? "").replace(/\s+/g, " ").trim();
-  if (text.length <= max)
-    return text;
-  if (max <= 3)
-    return text.slice(0, max);
-  return `${text.slice(0, max - 3)}...`;
-}
-function summarizeConfig(config, opts = {}) {
-  const summary = {
-    id: config.id,
-    slug: config.slug,
-    name: config.name,
-    category: config.category,
-    agent: config.agent,
-    kind: config.kind,
-    format: config.format,
-    target_path: config.target_path,
-    output_count: config.outputs.length,
-    version: config.version,
-    is_template: config.is_template
-  };
-  if (opts.verbose) {
-    summary.updated_at = config.updated_at;
-    summary.description = config.description;
-    summary.tags = config.tags;
-    summary.outputs = config.outputs;
-  }
-  return summary;
-}
-function summarizeProfile(profile, opts = {}) {
-  const selectorCount = (profile.selectors.os?.length ?? 0) + (profile.selectors.arch?.length ?? 0) + (profile.selectors.hostnames?.length ?? 0);
-  const summary = {
-    id: profile.id,
-    slug: profile.slug,
-    name: profile.name,
-    description: opts.verbose ? profile.description : truncateText(profile.description, 80),
-    selector_count: selectorCount,
-    variable_count: Object.keys(profile.variables).length
-  };
-  if (opts.verbose) {
-    summary.created_at = profile.created_at;
-    summary.updated_at = profile.updated_at;
-    summary.selectors = profile.selectors;
-    summary.variables = profile.variables;
-  }
-  return summary;
-}
-function summarizeApplyResult(result) {
-  return {
-    config_id: result.config_id,
-    path: result.path,
-    dry_run: result.dry_run,
-    changed: result.changed,
-    primary_changed: result.primary_changed,
-    agent: result.agent,
-    transform: result.transform,
-    output_count: result.outputs?.length ?? 0,
-    outputs: result.outputs?.map(summarizeApplyResult)
-  };
-}
-
-// src/mcp/server.ts
 var TOOL_DOCS = {
   list_configs: "List configs. Params: category?, agent?, kind?, search?, limit?, cursor?, verbose?. Defaults to a paged compact envelope without content; use get_config for full content.",
   get_config: "Get a config by id or slug. Returns full config including content.",