@thejoseki/clawform 2.3.1 → 2.4.0

package/src/commands/cost-report.js

@@ -1,166 +1,166 @@
-// clawform cost-report — month-to-date AWS spend, grouped by the Project / Env /
-// CostCenter tag (or by service). The POST-deploy half of cost governance:
-// cost-guard estimates before you commit a resource; this reads Cost Explorer
-// for what actually got billed, so a team without a FinOps function can see the
-// real number broken down the same way their stacks are tagged.
-//
-// Cost Explorer is a GLOBAL service with only a us-east-1 endpoint — the client
-// is pinned there regardless of the project's deploy region, and (unlike the
-// CFN commands) no AWS_REGION/AWS_PROFILE is *required*: the SDK's default
-// credential chain (env keys, SSO, instance role) is enough, which matters for
-// CI/cron use. CE bills ~$0.01 per GetCostAndUsage request; one logical query
-// per invocation (followed across NextPageToken pages — truncating silently
-// would understate the TOTAL, the one number this command exists to get right).
-//
-// Pure helpers (monthRange / groupByDef / parseCostRows / renderRows) are
-// exported and unit-tested without AWS; costReport() is the thin SDK wrapper.
-
-import { CostExplorerClient, GetCostAndUsageCommand } from '@aws-sdk/client-cost-explorer';
-import { logger } from '../lib/logger.js';
+// clawform cost-report — month-to-date AWS spend, grouped by the Project / Env /
+// CostCenter tag (or by service). The POST-deploy half of cost governance:
+// cost-guard estimates before you commit a resource; this reads Cost Explorer
+// for what actually got billed, so a team without a FinOps function can see the
+// real number broken down the same way their stacks are tagged.
+//
+// Cost Explorer is a GLOBAL service with only a us-east-1 endpoint — the client
+// is pinned there regardless of the project's deploy region, and (unlike the
+// CFN commands) no AWS_REGION/AWS_PROFILE is *required*: the SDK's default
+// credential chain (env keys, SSO, instance role) is enough, which matters for
+// CI/cron use. CE bills ~$0.01 per GetCostAndUsage request; one logical query
+// per invocation (followed across NextPageToken pages — truncating silently
+// would understate the TOTAL, the one number this command exists to get right).
+//
+// Pure helpers (monthRange / groupByDef / parseCostRows / renderRows) are
+// exported and unit-tested without AWS; costReport() is the thin SDK wrapper.
+
+import { CostExplorerClient, GetCostAndUsageCommand } from '@aws-sdk/client-cost-explorer';
+import { logger } from '../lib/logger.js';
 import { assertLicensed } from '../lib/license.js';
 import { resolveClient as resolveLicenseClient } from '../lib/license-client.js';
-
-const GROUP_BY = {
-  project: { Type: 'TAG', Key: 'Project' },
-  env: { Type: 'TAG', Key: 'Env' },
-  costcenter: { Type: 'TAG', Key: 'CostCenter' },
-  service: { Type: 'DIMENSION', Key: 'SERVICE' },
-};
-
-// Resolve the CE GroupBy definition. Defaults to the Project tag — the grouping
-// that matches how every clawform deploy tags its stacks (rules/tagging.md).
-export function groupByDef(groupBy = 'project') {
-  const key = String(groupBy).toLowerCase();
-  const def = GROUP_BY[key];
-  if (!def) {
-    throw new Error(`Unknown --group-by "${groupBy}". Expected one of: ${Object.keys(GROUP_BY).join(' | ')}.`);
-  }
-  return { key, def };
-}
-
-function pad2(n) { return String(n).padStart(2, '0'); }
-function ymd(d) { return `${d.getUTCFullYear()}-${pad2(d.getUTCMonth() + 1)}-${pad2(d.getUTCDate())}`; }
-
-// Compute the CE TimePeriod for a month. `month` is 'YYYY-MM' (defaults to the
-// month containing `today`). CE's End is EXCLUSIVE and may not be in the future,
-// so for the current month we clamp End to tomorrow (month-to-date); for a past
-// month End is the first of the next month (the full month).
-//
-// `today` is injected so the computation is deterministic in tests.
-export function monthRange(month, today) {
-  const now = today instanceof Date ? today : new Date();
-  let year, mon; // mon is 1-12
-  if (month) {
-    const m = /^(\d{4})-(\d{2})$/.exec(String(month).trim());
-    if (!m) throw new Error(`Invalid --month "${month}". Expected YYYY-MM.`);
-    year = Number(m[1]);
-    mon = Number(m[2]);
-    if (mon < 1 || mon > 12) throw new Error(`Invalid month number in "${month}".`);
-  } else {
-    year = now.getUTCFullYear();
-    mon = now.getUTCMonth() + 1;
-  }
-
-  const start = new Date(Date.UTC(year, mon - 1, 1));
-  const nextMonthFirst = new Date(Date.UTC(year, mon, 1));
-  const tomorrow = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + 1));
-
-  if (start >= tomorrow) {
-    throw new Error(`Month ${year}-${pad2(mon)} is in the future — no cost data yet.`);
-  }
-  const end = nextMonthFirst < tomorrow ? nextMonthFirst : tomorrow;
-  // "partial" = the reported month is still accruing charges, i.e. it's the
-  // current UTC month — NOT "end was clamped": on the month's last day the
-  // clamp is a no-op (tomorrow == nextMonthFirst) but today's spend is still
-  // incomplete, and the label must say so. All date math is UTC because Cost
-  // Explorer's day boundaries are UTC.
-  const partial = year === now.getUTCFullYear() && mon === now.getUTCMonth() + 1;
-  return { Start: ymd(start), End: ymd(end), label: `${year}-${pad2(mon)}`, partial };
-}
-
-// Flatten a CE GetCostAndUsage response into sorted rows. Sums each group key
-// across every period returned (we use MONTHLY granularity, so usually one).
-// TAG group keys arrive as "Project$value" — strip to the value; an empty value
-// becomes "(untagged)" so unallocated spend is visible, not hidden.
-export function parseCostRows(response) {
-  const totals = new Map();
-  let unit = 'USD';
-  for (const period of response?.ResultsByTime ?? []) {
-    for (const g of period.Groups ?? []) {
-      const rawKey = g.Keys?.[0] ?? '';
-      const value = rawKey.includes('$') ? rawKey.slice(rawKey.indexOf('$') + 1) : rawKey;
-      const key = value === '' ? '(untagged)' : value;
-      const metric = g.Metrics?.UnblendedCost ?? {};
-      const amount = Number(metric.Amount ?? 0);
-      if (metric.Unit) unit = metric.Unit;
-      totals.set(key, (totals.get(key) ?? 0) + (Number.isFinite(amount) ? amount : 0));
-    }
-  }
-  const rows = [...totals.entries()]
-    .map(([key, amount]) => ({ key, amount, unit }))
-    .sort((a, b) => b.amount - a.amount);
-  const total = rows.reduce((s, r) => s + r.amount, 0);
-  return { rows, total, unit };
-}
-
-export function renderRows({ rows, total, unit }, meta) {
-  const lines = [];
-  const span = meta.partial ? `${meta.label} (month-to-date)` : meta.label;
-  lines.push(`Cost by ${meta.groupBy} — ${span} — ${meta.Start} → ${meta.End} (exclusive)`);
-  lines.push('');
-  if (rows.length === 0) {
-    lines.push('  (no cost data for this period)');
-    return lines.join('\n');
-  }
-  const width = Math.max(8, ...rows.map((r) => r.key.length));
-  for (const r of rows) {
-    lines.push(`  ${r.key.padEnd(width)}  ${r.amount.toFixed(2).padStart(10)} ${r.unit}`);
-  }
-  lines.push('');
-  lines.push(`  ${'TOTAL'.padEnd(width)}  ${total.toFixed(2).padStart(10)} ${unit}`);
-
-  const untagged = rows.find((r) => r.key === '(untagged)');
-  if (untagged && total > 0 && untagged.amount / total > 0.5 && meta.def.Type === 'TAG') {
-    lines.push('');
-    lines.push(
-      `  Note: >50% of spend is (untagged) for tag "${meta.def.Key}". Activate it under ` +
-      `Billing → Cost allocation tags so per-${meta.groupBy} breakdown becomes meaningful ` +
-      `(activation is not retroactive).`,
-    );
-  }
-  return lines.join('\n');
-}
-
+
+const GROUP_BY = {
+  project: { Type: 'TAG', Key: 'Project' },
+  env: { Type: 'TAG', Key: 'Env' },
+  costcenter: { Type: 'TAG', Key: 'CostCenter' },
+  service: { Type: 'DIMENSION', Key: 'SERVICE' },
+};
+
+// Resolve the CE GroupBy definition. Defaults to the Project tag — the grouping
+// that matches how every clawform deploy tags its stacks (rules/tagging.md).
+export function groupByDef(groupBy = 'project') {
+  const key = String(groupBy).toLowerCase();
+  const def = GROUP_BY[key];
+  if (!def) {
+    throw new Error(`Unknown --group-by "${groupBy}". Expected one of: ${Object.keys(GROUP_BY).join(' | ')}.`);
+  }
+  return { key, def };
+}
+
+function pad2(n) { return String(n).padStart(2, '0'); }
+function ymd(d) { return `${d.getUTCFullYear()}-${pad2(d.getUTCMonth() + 1)}-${pad2(d.getUTCDate())}`; }
+
+// Compute the CE TimePeriod for a month. `month` is 'YYYY-MM' (defaults to the
+// month containing `today`). CE's End is EXCLUSIVE and may not be in the future,
+// so for the current month we clamp End to tomorrow (month-to-date); for a past
+// month End is the first of the next month (the full month).
+//
+// `today` is injected so the computation is deterministic in tests.
+export function monthRange(month, today) {
+  const now = today instanceof Date ? today : new Date();
+  let year, mon; // mon is 1-12
+  if (month) {
+    const m = /^(\d{4})-(\d{2})$/.exec(String(month).trim());
+    if (!m) throw new Error(`Invalid --month "${month}". Expected YYYY-MM.`);
+    year = Number(m[1]);
+    mon = Number(m[2]);
+    if (mon < 1 || mon > 12) throw new Error(`Invalid month number in "${month}".`);
+  } else {
+    year = now.getUTCFullYear();
+    mon = now.getUTCMonth() + 1;
+  }
+
+  const start = new Date(Date.UTC(year, mon - 1, 1));
+  const nextMonthFirst = new Date(Date.UTC(year, mon, 1));
+  const tomorrow = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + 1));
+
+  if (start >= tomorrow) {
+    throw new Error(`Month ${year}-${pad2(mon)} is in the future — no cost data yet.`);
+  }
+  const end = nextMonthFirst < tomorrow ? nextMonthFirst : tomorrow;
+  // "partial" = the reported month is still accruing charges, i.e. it's the
+  // current UTC month — NOT "end was clamped": on the month's last day the
+  // clamp is a no-op (tomorrow == nextMonthFirst) but today's spend is still
+  // incomplete, and the label must say so. All date math is UTC because Cost
+  // Explorer's day boundaries are UTC.
+  const partial = year === now.getUTCFullYear() && mon === now.getUTCMonth() + 1;
+  return { Start: ymd(start), End: ymd(end), label: `${year}-${pad2(mon)}`, partial };
+}
+
+// Flatten a CE GetCostAndUsage response into sorted rows. Sums each group key
+// across every period returned (we use MONTHLY granularity, so usually one).
+// TAG group keys arrive as "Project$value" — strip to the value; an empty value
+// becomes "(untagged)" so unallocated spend is visible, not hidden.
+export function parseCostRows(response) {
+  const totals = new Map();
+  let unit = 'USD';
+  for (const period of response?.ResultsByTime ?? []) {
+    for (const g of period.Groups ?? []) {
+      const rawKey = g.Keys?.[0] ?? '';
+      const value = rawKey.includes('$') ? rawKey.slice(rawKey.indexOf('$') + 1) : rawKey;
+      const key = value === '' ? '(untagged)' : value;
+      const metric = g.Metrics?.UnblendedCost ?? {};
+      const amount = Number(metric.Amount ?? 0);
+      if (metric.Unit) unit = metric.Unit;
+      totals.set(key, (totals.get(key) ?? 0) + (Number.isFinite(amount) ? amount : 0));
+    }
+  }
+  const rows = [...totals.entries()]
+    .map(([key, amount]) => ({ key, amount, unit }))
+    .sort((a, b) => b.amount - a.amount);
+  const total = rows.reduce((s, r) => s + r.amount, 0);
+  return { rows, total, unit };
+}
+
+export function renderRows({ rows, total, unit }, meta) {
+  const lines = [];
+  const span = meta.partial ? `${meta.label} (month-to-date)` : meta.label;
+  lines.push(`Cost by ${meta.groupBy} — ${span} — ${meta.Start} → ${meta.End} (exclusive)`);
+  lines.push('');
+  if (rows.length === 0) {
+    lines.push('  (no cost data for this period)');
+    return lines.join('\n');
+  }
+  const width = Math.max(8, ...rows.map((r) => r.key.length));
+  for (const r of rows) {
+    lines.push(`  ${r.key.padEnd(width)}  ${r.amount.toFixed(2).padStart(10)} ${r.unit}`);
+  }
+  lines.push('');
+  lines.push(`  ${'TOTAL'.padEnd(width)}  ${total.toFixed(2).padStart(10)} ${unit}`);
+
+  const untagged = rows.find((r) => r.key === '(untagged)');
+  if (untagged && total > 0 && untagged.amount / total > 0.5 && meta.def.Type === 'TAG') {
+    lines.push('');
+    lines.push(
+      `  Note: >50% of spend is (untagged) for tag "${meta.def.Key}". Activate it under ` +
+      `Billing → Cost allocation tags so per-${meta.groupBy} breakdown becomes meaningful ` +
+      `(activation is not retroactive).`,
+    );
+  }
+  return lines.join('\n');
+}
+
 export default async function costReport({ month, groupBy, profile, today } = {}) {
-  await assertLicensed({ command: 'cost-report', client: resolveLicenseClient() });
-  const { key, def } = groupByDef(groupBy);
-  const range = monthRange(month, today);
-
-  // Unlike the CFN commands, no profile/region is REQUIRED here: CE is global
-  // (us-east-1) and the SDK's default credential chain covers env keys / SSO /
-  // instance roles — the common CI shapes. An explicit --profile still wins.
-  if (profile) process.env.AWS_PROFILE = profile;
-
-  const client = new CostExplorerClient({ region: 'us-east-1' });
-
-  logger.step(`clawform cost-report — ${range.label} by ${key}`);
-
-  // GetCostAndUsage paginates via NextPageToken; follow it — a truncated group
-  // list silently understates the TOTAL.
-  const results = [];
-  let nextPageToken;
-  do {
-    const resp = await client.send(new GetCostAndUsageCommand({
-      TimePeriod: { Start: range.Start, End: range.End },
-      Granularity: 'MONTHLY',
-      Metrics: ['UnblendedCost'],
-      GroupBy: [def],
-      ...(nextPageToken ? { NextPageToken: nextPageToken } : {}),
-    }));
-    results.push(...(resp.ResultsByTime ?? []));
-    nextPageToken = resp.NextPageToken;
-  } while (nextPageToken);
-
-  const parsed = parseCostRows({ ResultsByTime: results });
-  console.log(renderRows(parsed, { ...range, groupBy: key, def }));
-}
+  await assertLicensed({ command: 'cost-report', client: resolveLicenseClient() });
+  const { key, def } = groupByDef(groupBy);
+  const range = monthRange(month, today);
+
+  // Unlike the CFN commands, no profile/region is REQUIRED here: CE is global
+  // (us-east-1) and the SDK's default credential chain covers env keys / SSO /
+  // instance roles — the common CI shapes. An explicit --profile still wins.
+  if (profile) process.env.AWS_PROFILE = profile;
+
+  const client = new CostExplorerClient({ region: 'us-east-1' });
+
+  logger.step(`clawform cost-report — ${range.label} by ${key}`);
+
+  // GetCostAndUsage paginates via NextPageToken; follow it — a truncated group
+  // list silently understates the TOTAL.
+  const results = [];
+  let nextPageToken;
+  do {
+    const resp = await client.send(new GetCostAndUsageCommand({
+      TimePeriod: { Start: range.Start, End: range.End },
+      Granularity: 'MONTHLY',
+      Metrics: ['UnblendedCost'],
+      GroupBy: [def],
+      ...(nextPageToken ? { NextPageToken: nextPageToken } : {}),
+    }));
+    results.push(...(resp.ResultsByTime ?? []));
+    nextPageToken = resp.NextPageToken;
+  } while (nextPageToken);
+
+  const parsed = parseCostRows({ ResultsByTime: results });
+  console.log(renderRows(parsed, { ...range, groupBy: key, def }));
+}

package/src/commands/deactivate.js

@@ -6,11 +6,18 @@
 
 import { logger } from '../lib/logger.js';
 import { resolveClient } from '../lib/license-client.js';
-import { readLicense, clearLicense } from '../lib/license-store.js';
+import { readLicenseRaw, clearLicense } from '../lib/license-store.js';
 
 export default async function deactivate(_opts = {}, {
   client = resolveClient(),
-  read = readLicense,
+  // Raw read on purpose: a record invalidated by a schema/version change still
+  // points at a live Polar slot. Reading it unsigned is what lets the owner
+  // reclaim that orphaned slot — the alternative strands it until support acts.
+  // Safe: deactivating grants nothing (see readLicenseRaw), and the vendor call
+  // is KEY-SCOPED — Polar only releases an instanceId that belongs to the key in
+  // the same record, so a hand-written record can only release activations of a
+  // key its author already holds, which is already full control of that licence.
+  read = readLicenseRaw,
   clear = clearLicense,
   log = (m) => logger.ok(m),
   warn = (m) => logger.warn(m),