@kynetic-ai/spec 0.10.0 → 0.12.0

package/dist/cli/commands/item.js

@@ -1,6 +1,6 @@
 import chalk from "chalk";
 import { markMutating } from "../command-annotations.js";
-import { AlignmentIndex, addChildItem, buildIndexes, checkSlugUniqueness, createNote, createSpecItem, deleteSpecItem, findChildItems, findDescendantItems, findTraitImplementors, initContext, loadAllItems, loadMetaContext, loadAllTasks, patchSpecItems, ReferenceIndex, resolveMetaRef, shortestUniqueUlid, updateSpecItem, } from "../../parser/index.js";
+import { AlignmentIndex, addProjectLevelTraitItem, addChildItem, buildIndexes, checkSlugUniqueness, createNote, createSpecItem, deleteSpecItem, findChildItems, findDescendantItems, findTraitImplementors, initContext, loadAllItems, loadMetaContext, loadAllTasks, patchSpecItems, ReferenceIndex, resolveMetaRef, shortestUniqueUlid, updateSpecItem, } from "../../parser/index.js";
 import { commitIfShadow } from "../../parser/shadow.js";
 import { SpecItemPatchSchema } from "../../schema/index.js";
 import { ImplementationStatusSchema, MaturitySchema, } from "../../schema/common.js";
@@ -8,8 +8,22 @@ import { errors } from "../../strings/errors.js";
 import { fieldLabels, sectionHeaders } from "../../strings/labels.js";
 import { formatMatchedFields, grepItem } from "../../utils/grep.js";
 import { EXIT_CODES } from "../exit-codes.js";
-import { error, isJsonMode, output, success, warn } from "../output.js";
+import { error, isJsonMode, output, showChangeDiff, success, warn } from "../output.js";
 import { parseTagsArray } from "../parse-utils.js";
+/**
+ * Serialize a LoadedSpecItem for JSON output.
+ * Strips internal fields (_sourceFile, _path), renames _ulid → ulid,
+ * and adds a ref field with @ prefix for the primary slug.
+ * AC: @trait-json-output ac-4
+ */
+function serializeSpecItemForJson(item) {
+    const { _sourceFile, _path, _ulid, ...rest } = item;
+    return {
+        ulid: _ulid,
+        ref: item.slugs.length > 0 ? `@${item.slugs[0]}` : `@${_ulid}`,
+        ...rest,
+    };
+}
 /**
  * Format a spec item for display
  */
@@ -290,12 +304,9 @@ export function registerItemCommands(program) {
                 return;
             }
             output({
-                items: specItems,
+                items: specItems.map(serializeSpecItemForJson),
                 total: effectiveTotal,
                 showing: specItems.length,
-                grepPattern: options.grep,
-                tree: options.tree,
-                under: options.under,
             }, () => {
                 if (options.tree) {
                     // AC: @module-scoped-item-listing ac-under-with-tree
@@ -347,7 +358,7 @@ export function registerItemCommands(program) {
             }
             // Build JSON output with inherited traits
             const jsonOutput = {
-                ...item,
+                ...serializeSpecItemForJson(item),
                 inherited_traits: Array.from(traitsByTrait.values()).map(({ trait, acs }) => ({
                     ref: `@${trait.slug}`,
                     title: trait.title,
@@ -493,8 +504,9 @@ export function registerItemCommands(program) {
     });
     // kspec item add - create a new spec item under a parent
     markMutating(item.command("add"))
-        .description("Create a new spec item under a parent")
-        .requiredOption("--under <ref>", "Parent item reference (e.g., @core-primitives)")
+        .description("Create a new spec item under a parent or in project root")
+        .option("--under <ref>", "Parent item reference (e.g., @core-primitives)")
+        .option("--root", "Create at project root (trait items only)")
         .requiredOption("--title <title>", "Item title")
         .option("--type <type>", "Item type (feature, requirement, constraint, decision)", "feature")
         .option("--slug <slug>", "Human-friendly slug")
@@ -507,22 +519,47 @@ export function registerItemCommands(program) {
 Examples:
   $ kspec item add --under @parent --title "Feature name" --type feature
   $ kspec item add --under @parent --title "Multi-tag" --tag api public
-  $ kspec item add --under @parent --title "API endpoint" --trait @trait-api-endpoint`)
+  $ kspec item add --under @parent --title "API endpoint" --trait @trait-api-endpoint
+  $ kspec item add --root --type trait --title "JSON Output" --slug trait-json-output`)
         .action(async (options) => {
         try {
             const ctx = await initContext();
             const { refIndex, items } = await buildIndexes(ctx);
-            // Find the parent item
-            const parentResult = refIndex.resolve(options.under);
-            if (!parentResult.ok) {
-                error(errors.reference.itemNotFound(options.under));
-                process.exit(EXIT_CODES.ERROR);
+            const isRootAdd = Boolean(options.root);
+            const itemType = options.type;
+            const exitWithUsageGuidance = (message, suggestion, details) => {
+                error(message, { suggestion, ...details });
+                process.exit(EXIT_CODES.USAGE_ERROR);
+            };
+            if (options.under && isRootAdd) {
+                exitWithUsageGuidance(`Cannot use --under (${options.under}) and --root together`, "Use --root only for project-level traits in kynetic.yaml, or remove --root and keep --under for nested items.", {
+                    field: "under",
+                    value: options.under,
+                    conflicting_field: "root",
+                });
             }
-            const parent = parentResult.item;
-            // Check it's not a task
-            if ("status" in parent && typeof parent.status === "string") {
-                error(errors.reference.parentIsTask(options.under));
-                process.exit(EXIT_CODES.ERROR);
+            if (!options.under && !isRootAdd) {
+                exitWithUsageGuidance("item add requires either --under <ref> or --root", "Use --under @parent to create a nested item, or use --root --type trait to create a project-level trait in kynetic.yaml.");
+            }
+            if (isRootAdd && itemType !== "trait") {
+                exitWithUsageGuidance(`--root is only supported for --type trait (received: ${itemType || "undefined"})`, "Change --type to trait for project-level creation, or remove --root and create the item under a parent with --under.", {
+                    field: "type",
+                    value: itemType || null,
+                });
+            }
+            let parent = null;
+            if (options.under) {
+                const parentResult = refIndex.resolve(options.under);
+                if (!parentResult.ok) {
+                    error(errors.reference.itemNotFound(options.under));
+                    process.exit(EXIT_CODES.ERROR);
+                }
+                parent = parentResult.item;
+                // Check it's not a task
+                if ("status" in parent && typeof parent.status === "string") {
+                    error(errors.reference.parentIsTask(options.under));
+                    process.exit(EXIT_CODES.ERROR);
+                }
             }
             // Check slug uniqueness if provided
             if (options.slug) {
@@ -565,7 +602,7 @@ Examples:
             }
             const input = {
                 title: options.title,
-                type: options.type,
+                type: itemType,
                 slugs: options.slug ? [options.slug] : [],
                 priority: options.priority,
                 tags: parseTagsArray(options.tag),
@@ -578,20 +615,32 @@ Examples:
                 notes: [],
             };
             const newItem = createSpecItem(input);
-            const result = await addChildItem(ctx, parent, newItem, options.as);
+            const addResult = isRootAdd
+                ? await addProjectLevelTraitItem(ctx, newItem)
+                : await addChildItem(ctx, parent, newItem, options.as);
+            const resultItem = {
+                ...addResult.item,
+                ...(isRootAdd
+                    ? {
+                        _sourceFile: ctx.manifestPath,
+                        _path: addResult.path,
+                    }
+                    : {}),
+            };
             // Build index including the new item for accurate short ULID
-            const index = new ReferenceIndex([], [...items, result.item]);
-            const itemSlug = result.item.slugs?.[0] ||
-                index.shortUlid(result.item._ulid);
+            const index = new ReferenceIndex([], [...items, resultItem]);
+            const itemSlug = resultItem.slugs?.[0] || index.shortUlid(resultItem._ulid);
+            const itemRef = `@${itemSlug}`;
             await commitIfShadow(ctx.shadow, "item-add", itemSlug);
-            success(`Created item: ${index.shortUlid(result.item._ulid)} under @${parent.slugs[0] || index.shortUlid(parent._ulid)}`, {
-                item: result.item,
-                path: result.path,
+            success(isRootAdd
+                ? `Created item: ${itemRef} in project root traits`
+                : `Created item: ${index.shortUlid(resultItem._ulid)} under @${parent.slugs[0] || index.shortUlid(parent._ulid)}`, {
+                item: resultItem,
+                path: addResult.path,
             });
             // Derive hint
             if (!isJsonMode()) {
-                const refSlug = result.item.slugs?.[0] ||
-                    index.shortUlid(result.item._ulid);
+                const refSlug = resultItem.slugs?.[0] || index.shortUlid(resultItem._ulid);
                 console.log(chalk.gray(`\nDerive implementation task? kspec derive @${refSlug}`));
             }
         }
@@ -615,20 +664,27 @@ Examples:
         .option("--verified-by <agent-ref>", "Set verified_by (for retrospective specs)")
         .option("--verified-at <iso-timestamp>", "Set verified_at (defaults to now if --verified-by provided)")
         .option("--trait <trait...>", "Set traits (replaces existing)")
+        .option("--add-trait <trait...>", "Add traits (appends to existing)")
+        .option("--remove-trait <trait...>", "Remove specific traits")
+        .option("--clear-traits", "Clear all traits")
         .option("--relates-to <ref>", "Add a relates_to reference")
         .option("--implements <ref>", "Add an implements reference")
         .option("--depends-on <ref>", "Add a depends_on reference")
         .option("--clear-relates-to", "Clear all relates_to references")
         .option("--clear-implements", "Clear all implements references")
         .option("--clear-depends-on", "Clear all depends_on references")
+        .option("--no-cascade", "Skip child status cascade prompt (apply change only to target item)")
         .addHelpText("after", `
 Examples:
   $ kspec item set @item-ref --title "New title"
   $ kspec item set @item-ref --tag api internal security
-  $ kspec item set @item-ref --trait reusable testable
+  $ kspec item set @item-ref --trait @reusable @testable  # replaces all traits
+  $ kspec item set @item-ref --add-trait @json-output     # appends trait
+  $ kspec item set @item-ref --remove-trait @old-trait     # removes trait
   $ kspec item set @item-ref --relates-to @other-item
   $ kspec item set @item-ref --implements @feature-spec
-  $ kspec item set @item-ref --depends-on @prereq-spec`)
+  $ kspec item set @item-ref --depends-on @prereq-spec
+  $ kspec item set @item-ref --status implemented --no-cascade`)
         .action(async (ref, options) => {
         try {
             const ctx = await initContext();
@@ -678,6 +734,41 @@ Examples:
                 error("Cannot use --depends-on and --clear-depends-on together");
                 process.exit(EXIT_CODES.USAGE_ERROR);
             }
+            // Mutual exclusivity for trait flags
+            const traitFlagCount = [options.trait, options.addTrait, options.removeTrait, options.clearTraits].filter(Boolean).length;
+            if (traitFlagCount > 1) {
+                error("Cannot combine --trait, --add-trait, --remove-trait, and --clear-traits. Use only one at a time.");
+                process.exit(EXIT_CODES.USAGE_ERROR);
+            }
+            // Helper to validate and canonicalize a list of trait refs
+            const validateTraitRefs = (traitRefs) => {
+                const validated = [];
+                const seenUlids = new Set();
+                let hasErrors = false;
+                for (const traitRef of traitRefs) {
+                    const traitResult = refIndex.resolve(traitRef);
+                    if (!traitResult.ok) {
+                        error(`Trait not found: ${traitRef}`);
+                        hasErrors = true;
+                        continue;
+                    }
+                    const traitItem = traitResult.item;
+                    if (traitItem.type !== "trait") {
+                        error(`${traitRef} is not a trait (type: ${traitItem.type})`);
+                        hasErrors = true;
+                        continue;
+                    }
+                    if (seenUlids.has(traitItem._ulid))
+                        continue;
+                    seenUlids.add(traitItem._ulid);
+                    const canonicalRef = `@${traitItem.slugs[0] || traitItem._ulid}`;
+                    validated.push(canonicalRef);
+                }
+                if (hasErrors) {
+                    process.exit(EXIT_CODES.NOT_FOUND);
+                }
+                return validated;
+            };
             // Helper to validate relationship refs (must exist and be a spec item, not a task)
             // Returns { ulid, canonicalRef } for deduplication and user-friendly storage
             const validateRelationshipRef = (refStr, flagName) => {
@@ -744,8 +835,46 @@ Examples:
                 updates.priority = options.priority;
             if (options.tag)
                 updates.tags = parseTagsArray(options.tag);
-            if (options.trait)
-                updates.traits = options.trait;
+            // Handle trait mutations (--trait replaces, --add-trait appends, --remove-trait removes, --clear-traits clears)
+            if (options.trait) {
+                updates.traits = validateTraitRefs(options.trait);
+            }
+            else if (options.addTrait) {
+                const validated = validateTraitRefs(options.addTrait);
+                const current = foundItem.traits || [];
+                // Resolve existing traits to ULIDs for deduplication
+                const existingUlids = new Set();
+                for (const ref of current) {
+                    const result = refIndex.resolve(ref);
+                    if (result.ok)
+                        existingUlids.add(result.ulid);
+                }
+                const newTraits = validated.filter((ref) => {
+                    const result = refIndex.resolve(ref);
+                    return result.ok && !existingUlids.has(result.ulid);
+                });
+                if (newTraits.length > 0) {
+                    updates.traits = [...current, ...newTraits];
+                }
+            }
+            else if (options.removeTrait) {
+                const validated = validateTraitRefs(options.removeTrait);
+                const current = foundItem.traits || [];
+                // Resolve removal targets to ULIDs
+                const removeUlids = new Set();
+                for (const ref of validated) {
+                    const result = refIndex.resolve(ref);
+                    if (result.ok)
+                        removeUlids.add(result.ulid);
+                }
+                updates.traits = current.filter((ref) => {
+                    const result = refIndex.resolve(ref);
+                    return !result.ok || !removeUlids.has(result.ulid);
+                });
+            }
+            else if (options.clearTraits) {
+                updates.traits = [];
+            }
             if (options.description)
                 updates.description = options.description;
             // AC: @implementation-states ac-reject-invalid
@@ -825,18 +954,35 @@ Examples:
                 warn("No updates specified");
                 return;
             }
+            // Build before→after changes for display
+            const changes = [];
+            for (const [key, value] of Object.entries(updates)) {
+                const before = foundItem[key];
+                // Only record if value actually changed
+                if (JSON.stringify(before) !== JSON.stringify(value)) {
+                    changes.push({ field: key, before, after: value });
+                }
+            }
+            if (changes.length === 0) {
+                warn("No changes: values are already set to the specified values");
+                return;
+            }
             const updated = await updateSpecItem(ctx, foundItem, updates);
             const itemSlug = foundItem.slugs[0] || refIndex.shortUlid(foundItem._ulid);
             // Handle cascade for implementation status updates
             const updatedItems = [updated];
-            if (options.status) {
+            if (options.status && options.cascade !== false) {
                 const cascadeResult = await handleStatusCascade(ctx, updated, options.status, items, refIndex);
                 updatedItems.push(...cascadeResult);
             }
             await commitIfShadow(ctx.shadow, "item-set", itemSlug);
-            success(`Updated item: ${refIndex.shortUlid(updated._ulid)}`, {
+            const changedFields = changes.map((c) => c.field).join(", ");
+            success(`Updated item: ${refIndex.shortUlid(updated._ulid)} (${changedFields})`, {
                 item: updated,
+                changes,
             });
+            // Show before→after diff in text mode
+            showChangeDiff(changes);
             // Derive hint
             if (!isJsonMode()) {
                 const refSlug = updated.slugs?.[0] || refIndex.shortUlid(updated._ulid);
@@ -1403,9 +1549,10 @@ Examples:
                 error(errors.conflict.acIdAlreadyExists(options.id));
                 process.exit(EXIT_CODES.CONFLICT);
             }
-            // Build updated AC
+            // Build updated AC and track before→after changes
             const updatedAc = [...existingAc];
-            const updatedFields = [];
+            const originalAc = { ...updatedAc[acIndex] };
+            const changes = [];
             updatedAc[acIndex] = {
                 ...updatedAc[acIndex],
                 ...(options.id && { id: options.id }),
@@ -1413,19 +1560,30 @@ Examples:
                 ...(options.when && { when: options.when }),
                 ...(options.then && { then: options.then }),
             };
-            if (options.id)
-                updatedFields.push("id");
-            if (options.given)
-                updatedFields.push("given");
-            if (options.when)
-                updatedFields.push("when");
-            if (options.then)
-                updatedFields.push("then");
+            if (options.id && options.id !== originalAc.id) {
+                changes.push({ field: "id", before: originalAc.id, after: options.id });
+            }
+            if (options.given && options.given !== originalAc.given) {
+                changes.push({ field: "given", before: originalAc.given, after: options.given });
+            }
+            if (options.when && options.when !== originalAc.when) {
+                changes.push({ field: "when", before: originalAc.when, after: options.when });
+            }
+            if (options.then && options.then !== originalAc.then) {
+                changes.push({ field: "then", before: originalAc.then, after: options.then });
+            }
+            if (changes.length === 0) {
+                warn("No changes: values are already set to the specified values");
+                return;
+            }
             // Update item
             await updateSpecItem(ctx, item, { acceptance_criteria: updatedAc });
             const itemSlug = item.slugs[0] || refIndex.shortUlid(item._ulid);
             await commitIfShadow(ctx.shadow, "item-ac-set", itemSlug);
-            success(`Updated acceptance criterion: ${acId} on @${itemSlug} (${updatedFields.join(", ")})`, { ac: updatedAc[acIndex] });
+            const changedFields = changes.map((c) => c.field).join(", ");
+            success(`Updated acceptance criterion: ${acId} on @${itemSlug} (${changedFields})`, { ac: updatedAc[acIndex], changes });
+            // Show before→after diff in text mode
+            showChangeDiff(changes);
         }
         catch (err) {
             error(errors.failures.updateAc, err);