@kici-dev/compiler 0.6.0 → 0.6.1

package/dist/cli.js

@@ -7,7 +7,7 @@ import { realpathSync } from "node:fs";
 import { Argument, Command } from "commander";
 import pc from "picocolors";
 //#region src/cli.ts
-const version = "0.6.0";
+const version = "0.6.1";
 /**
 * Top-level commands that were removed, mapped to their current equivalent.
 * Consulted when the CLI hits an unknown command so the user gets a precise
@@ -484,7 +484,7 @@ Environment variables:
 		const { docsCommand } = await import("./commands/index.js");
 		const success = await docsCommand({ open: options.open });
 		process.exit(success ? 0 : 1);
-	}).command("llm [topic]").description("Print KiCI LLM docs bundles. No topic prints the llms.txt index; <topic> prints a task bundle (e.g. sdk, cli, patterns, features, providers, architecture, getting-started); \"full\" prints the complete bundle.").option("--out <path>", "Write the bundle to a file instead of stdout").action(async (topic, options) => {
+	}).command("llm [topic]").description("Print KiCI LLM docs bundles. No topic prints the llms.txt index; <topic> prints a task bundle (e.g. sdk, cli, cli-remote, patterns, features, providers, architecture, getting-started); \"full\" prints the complete bundle.").option("--out <path>", "Write the bundle to a file instead of stdout").action(async (topic, options) => {
 		const { docsLlmCommand } = await import("./commands/index.js");
 		const success = await docsLlmCommand({
 			topic,
@@ -492,6 +492,14 @@ Environment variables:
 		});
 		process.exit(success ? 0 : 1);
 	});
+	program.command("feedback").description("Print how to report a discrepancy between what KiCI advertises and what it does. Files nothing.").option("--open", "Open the prefilled issue form in the default browser").option("--json", "Emit the reporting contract as JSON").action(async (options) => {
+		const { feedbackCommand } = await import("./commands/index.js");
+		const success = await feedbackCommand({
+			open: options.open,
+			json: options.json
+		});
+		process.exit(success ? 0 : 1);
+	});
 	program.command("admin").description("Operator-facing commands for running instances").command("drain-worker").description("Trigger graceful drain on a worker instance").requiredOption("--url <url>", "Worker URL (e.g., http://worker-host:<port>)").action(async (options) => {
 		const { drainWorkerCommand } = await import("./commands/index.js");
 		const success = await drainWorkerCommand({ url: options.url });

package/dist/commands/feedback.d.ts

@@ -0,0 +1,53 @@
+/** The public tracker. Reports about KiCI itself go here — never customer data. */
+export declare const FEEDBACK_TRACKER_URL = "https://github.com/kici-dev/kici-public";
+/** The issue form tuned for an advertised-versus-actual report. */
+export declare const FEEDBACK_TEMPLATE = "agent_report.yml";
+export declare const FEEDBACK_NEW_ISSUE_URL = "https://github.com/kici-dev/kici-public/issues/new?template=agent_report.yml";
+/** Suspected vulnerabilities go here instead, privately. */
+export declare const FEEDBACK_SECURITY_ADVISORY_URL = "https://github.com/kici-dev/kici-public/security/advisories/new";
+export interface FeedbackField {
+    id: string;
+    label: string;
+    description: string;
+}
+export interface FeedbackContract {
+    tracker: string;
+    newIssueUrl: string;
+    template: string;
+    securityAdvisoryUrl: string;
+    guideUrl: string;
+    searchCommand: string;
+    approval: {
+        required: boolean;
+        rule: string;
+    };
+    qualifies: string[];
+    doesNotQualify: string[];
+    requiredFields: FeedbackField[];
+    prohibited: string[];
+    privateReportCommand: string;
+}
+/**
+ * The single definition of what a reportable discrepancy is and what a report
+ * must carry. `kici feedback` prints it, `--json` emits it verbatim, and
+ * hack/feedback-contract.test.ts asserts the published guide says the same
+ * thing — so the CLI and the doc cannot drift apart.
+ */
+export declare const FEEDBACK_CONTRACT: FeedbackContract;
+export interface FeedbackOptions {
+    /** Open the prefilled issue form in the default browser. */
+    open?: boolean;
+    /** Emit the contract as JSON on stdout instead of prose. */
+    json?: boolean;
+}
+/**
+ * Print the contract for reporting a KiCI discrepancy: what qualifies, what a
+ * report must carry, what must never appear in a public issue, and the rule
+ * that an agent drafts a report but a human decides to file it.
+ *
+ * The command reaches no network and files nothing. `--open` opens the
+ * prefilled issue form; `--json` emits the same contract for an agent to
+ * consume without parsing prose.
+ */
+export declare function feedbackCommand(options?: FeedbackOptions): Promise<boolean>;
+//# sourceMappingURL=feedback.d.ts.map

package/dist/commands/feedback.js

@@ -0,0 +1,142 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import pc from "picocolors";
+import { logger, toErrorMessage } from "@kici-dev/core";
+import open from "open";
+//#region src/commands/feedback.ts
+/** The public tracker. Reports about KiCI itself go here — never customer data. */
+const FEEDBACK_TRACKER_URL = "https://github.com/kici-dev/kici-public";
+/** The issue form tuned for an advertised-versus-actual report. */
+const FEEDBACK_TEMPLATE = "agent_report.yml";
+const FEEDBACK_NEW_ISSUE_URL = `${FEEDBACK_TRACKER_URL}/issues/new?template=${FEEDBACK_TEMPLATE}`;
+/** Suspected vulnerabilities go here instead, privately. */
+const FEEDBACK_SECURITY_ADVISORY_URL = `${FEEDBACK_TRACKER_URL}/security/advisories/new`;
+/**
+* The single definition of what a reportable discrepancy is and what a report
+* must carry. `kici feedback` prints it, `--json` emits it verbatim, and
+* hack/feedback-contract.test.ts asserts the published guide says the same
+* thing — so the CLI and the doc cannot drift apart.
+*/
+const FEEDBACK_CONTRACT = {
+	tracker: FEEDBACK_TRACKER_URL,
+	newIssueUrl: FEEDBACK_NEW_ISSUE_URL,
+	template: FEEDBACK_TEMPLATE,
+	securityAdvisoryUrl: FEEDBACK_SECURITY_ADVISORY_URL,
+	guideUrl: "https://kici.dev/docs/user/reporting-discrepancies/",
+	searchCommand: "gh issue list --repo kici-dev/kici-public --search \"<terms>\" --state all",
+	approval: {
+		required: true,
+		rule: "Draft the issue, show the full body to the person you are working with, and file it only after they say yes."
+	},
+	qualifies: [
+		"A documented flag, command, or option that does not exist in the version you ran.",
+		"Documented output — a shape, a field, an exit code — that differs from what the command produced.",
+		"A CLI --help description that contradicts the published docs.",
+		"A documented behaviour that does not happen, or a documented guarantee that does not hold.",
+		"A documented error or limit that the tool does not actually enforce."
+	],
+	doesNotQualify: [
+		"Usage questions, or behaviour you find surprising but that the docs describe correctly.",
+		"Feature requests and design preferences.",
+		"Anything you inferred from reading docs without running the command.",
+		"Anything reproduced only on a locally built or unreleased version.",
+		"A failure that is your workflow, your credentials, or your environment."
+	],
+	requiredFields: [
+		{
+			id: "advertised",
+			label: "What the docs or CLI advertise",
+			description: "The exact claim, quoted, plus its source: a docs URL or the command whose --help says it."
+		},
+		{
+			id: "observed",
+			label: "What actually happened",
+			description: "The real output or behaviour, quoted, with any error text."
+		},
+		{
+			id: "reproduction",
+			label: "Minimal reproduction, including setup",
+			description: "Every step from an empty directory: the setup commands, a minimal synthetic workflow, and the exact command you ran."
+		},
+		{
+			id: "version",
+			label: "Version and environment",
+			description: "Output of `kici --version`, plus Node version and OS."
+		},
+		{
+			id: "justification",
+			label: "Why this is a discrepancy",
+			description: "One or two sentences ruling out the likely misreads — why the docs cannot be read to match what you observed."
+		}
+	],
+	prohibited: [
+		"No secrets, tokens, or credentials — not even redacted-looking ones.",
+		"No private repository names, internal hostnames, organization ids, or run ids.",
+		"No log excerpts you have not read line by line.",
+		"Reproduce with a minimal synthetic workflow, never the real one you were working on."
+	],
+	privateReportCommand: "kici report --run <run-id> --upload"
+};
+function printContract() {
+	const c = FEEDBACK_CONTRACT;
+	logger.info(pc.bold("Reporting a KiCI discrepancy"));
+	logger.info("");
+	logger.info("Use this when the published docs or the CLI advertise one behaviour and KiCI does another.");
+	logger.info(`Tracker: ${c.tracker}`);
+	logger.info(`Full guide: ${c.guideUrl}`);
+	logger.info("");
+	logger.info(pc.bold("1. Search first"));
+	logger.info("Comment on an existing report rather than opening a second one.");
+	logger.info(`  ${c.searchCommand}`);
+	logger.info("");
+	logger.info(pc.bold("2. Check it qualifies"));
+	for (const item of c.qualifies) logger.info(`  ${pc.green("+")} ${item}`);
+	logger.info("  Not a discrepancy:");
+	for (const item of c.doesNotQualify) logger.info(`  ${pc.gray("-")} ${item}`);
+	logger.info("");
+	logger.info(pc.bold("3. Never file these publicly"));
+	logger.info(`  A suspected vulnerability is never a public issue — open a private advisory instead:\n    ${c.securityAdvisoryUrl}`);
+	logger.info(`  A problem with your own runs is not a tracker issue — send it privately instead:\n    ${c.privateReportCommand}`);
+	for (const rule of c.prohibited) logger.info(`  ${pc.yellow("!")} ${rule}`);
+	logger.info("");
+	logger.info(pc.bold("4. Draft the report"));
+	for (const field of c.requiredFields) {
+		logger.info(`  ${field.label}`);
+		logger.info(pc.gray(`    ${field.description}`));
+	}
+	logger.info("");
+	logger.info(pc.bold("5. Get approval, then file"));
+	logger.info(`  ${c.approval.rule}`);
+	logger.info(`  Form: ${c.newIssueUrl}`);
+	logger.info(pc.gray(`  Or: kici feedback --open`));
+	logger.info("");
+	logger.info(pc.gray("Machine-readable: kici feedback --json"));
+}
+/**
+* Print the contract for reporting a KiCI discrepancy: what qualifies, what a
+* report must carry, what must never appear in a public issue, and the rule
+* that an agent drafts a report but a human decides to file it.
+*
+* The command reaches no network and files nothing. `--open` opens the
+* prefilled issue form; `--json` emits the same contract for an agent to
+* consume without parsing prose.
+*/
+async function feedbackCommand(options = {}) {
+	if (options.json) {
+		process.stdout.write(`${JSON.stringify(FEEDBACK_CONTRACT, null, 2)}\n`);
+		return true;
+	}
+	printContract();
+	if (!options.open) return true;
+	try {
+		await open(FEEDBACK_NEW_ISSUE_URL);
+		return true;
+	} catch (error) {
+		logger.error(pc.red(`Could not open a browser: ${toErrorMessage(error)}`));
+		logger.info(pc.gray(`Open ${FEEDBACK_NEW_ISSUE_URL} manually.`));
+		return false;
+	}
+}
+//#endregion
+export { FEEDBACK_CONTRACT, FEEDBACK_NEW_ISSUE_URL, FEEDBACK_SECURITY_ADVISORY_URL, FEEDBACK_TEMPLATE, FEEDBACK_TRACKER_URL, feedbackCommand };
+
+//# sourceMappingURL=feedback.js.map

package/dist/commands/index.d.ts

@@ -57,7 +57,9 @@ export type { WorkflowsListOptions } from './workflows.js';
 export { drainWorkerCommand } from './drain-worker.js';
 export type { DrainWorkerOptions } from './drain-worker.js';
 export { docsCommand, docsLlmCommand } from './docs.js';
+export { feedbackCommand, FEEDBACK_CONTRACT } from './feedback.js';
 export type { DocsOptions, DocsLlmOptions } from './docs.js';
+export type { FeedbackOptions, FeedbackContract, FeedbackField } from './feedback.js';
 export { verifyAttestationCommand } from './verify-attestation.js';
 export type { VerifyAttestationOptions } from './verify-attestation.js';
 export { notificationsChannelsListCommand, notificationsChannelsAddCommand, notificationsChannelsRemoveCommand, notificationsSubscriptionsListCommand, notificationsSubscriptionsAddCommand, notificationsSubscriptionsRemoveCommand, notificationsRosterListCommand, notificationsRosterAddCommand, notificationsRosterRemoveCommand, } from './notifications.js';

package/dist/commands/index.js

@@ -6,6 +6,7 @@ import { docsCommand, docsLlmCommand } from "./docs.js";
 import { doctorCommand } from "./doctor.js";
 import { drainWorkerCommand } from "./drain-worker.js";
 import { endpointsCommand } from "./endpoints.js";
+import { FEEDBACK_CONTRACT, feedbackCommand } from "./feedback.js";
 import { fixtureCommand } from "./fixture.js";
 import { hookInstallCommand } from "./hook.js";
 import { watchCommand } from "./watch.js";
@@ -34,4 +35,4 @@ import { rejectCommand } from "./reject.js";
 import { workflowsListCommand } from "./workflows.js";
 import { verifyAttestationCommand } from "./verify-attestation.js";
 import { notificationsChannelsAddCommand, notificationsChannelsListCommand, notificationsChannelsRemoveCommand, notificationsRosterAddCommand, notificationsRosterListCommand, notificationsRosterRemoveCommand, notificationsSubscriptionsAddCommand, notificationsSubscriptionsListCommand, notificationsSubscriptionsRemoveCommand } from "./notifications.js";
-export { approveCommand, compileCommand, diagnosticsCommand, docsCommand, docsLlmCommand, doctorCommand, drainWorkerCommand, endpointsCommand, fixtureCommand, hookInstallCommand, initCommand, localAttachCommand, localDetachCommand, localDownCommand, localLogsCommand, localStatusCommand, localTrustRootCommand, localUpCommand, loginCommand, logoutCommand, notificationsChannelsAddCommand, notificationsChannelsListCommand, notificationsChannelsRemoveCommand, notificationsRosterAddCommand, notificationsRosterListCommand, notificationsRosterRemoveCommand, notificationsSubscriptionsAddCommand, notificationsSubscriptionsListCommand, notificationsSubscriptionsRemoveCommand, orchestratorsListCommand, orchestratorsUseCommand, orgCurrentCommand, orgListCommand, orgUseCommand, patCreateCommand, previewCommand, previewEvent, rejectCommand, reportCommand, reportListCommand, reportWithdrawCommand, runRemoteCommand, runRoutedCommand, runsArtifactsDownloadCommand, runsArtifactsListCommand, runsCancelCommand, runsListCommand, runsLogsCommand, runsRerunCommand, runsShowCommand, secretsListCommand, typesCommand, verifyAttestationCommand, watchCommand, workflowsListCommand };
+export { FEEDBACK_CONTRACT, approveCommand, compileCommand, diagnosticsCommand, docsCommand, docsLlmCommand, doctorCommand, drainWorkerCommand, endpointsCommand, feedbackCommand, fixtureCommand, hookInstallCommand, initCommand, localAttachCommand, localDetachCommand, localDownCommand, localLogsCommand, localStatusCommand, localTrustRootCommand, localUpCommand, loginCommand, logoutCommand, notificationsChannelsAddCommand, notificationsChannelsListCommand, notificationsChannelsRemoveCommand, notificationsRosterAddCommand, notificationsRosterListCommand, notificationsRosterRemoveCommand, notificationsSubscriptionsAddCommand, notificationsSubscriptionsListCommand, notificationsSubscriptionsRemoveCommand, orchestratorsListCommand, orchestratorsUseCommand, orgCurrentCommand, orgListCommand, orgUseCommand, patCreateCommand, previewCommand, previewEvent, rejectCommand, reportCommand, reportListCommand, reportWithdrawCommand, runRemoteCommand, runRoutedCommand, runsArtifactsDownloadCommand, runsArtifactsListCommand, runsCancelCommand, runsListCommand, runsLogsCommand, runsRerunCommand, runsShowCommand, secretsListCommand, typesCommand, verifyAttestationCommand, watchCommand, workflowsListCommand };

package/dist/commands/report/identity.js

@@ -19,7 +19,7 @@ import { PROTOCOL_VERSION } from "@kici-dev/engine";
 */
 function collectIdentity(probe) {
 	const identity = {
-		kiciCliVersion: "0.6.0",
+		kiciCliVersion: "0.6.1",
 		nodeVersion: process.version,
 		platform: process.platform,
 		arch: process.arch,