chofex-cli 0.1.78 → 0.1.79

package/dist/index.js

@@ -59698,7 +59698,7 @@ var registrationPartsText = (result3) => {
 
 // src/cli-root.ts
 var root = exports_Command.make("chofex").pipe(exports_Command.withSharedFlags({
-  apiUrl: exports_Flag.string("api-url").pipe(exports_Flag.withDefault(config.apiUrl), exports_Flag.withDescription("Registration API base URL")),
+  apiUrl: exports_Flag.string("api-url").pipe(exports_Flag.withDefault(config.apiUrl), exports_Flag.withDescription("Chofex API base URL")),
   output: exports_Flag.choice("output", ["human", "json"]).pipe(exports_Flag.withDefault("human"), exports_Flag.withDescription("Output format")),
   token: exports_Flag.string("token").pipe(exports_Flag.optional, exports_Flag.withDescription("Clerk OAuth token (prefer CHOFEX_TOKEN to avoid shell history)"))
 }), exports_Command.withDescription("Register for and manage your Chofex hackathon application"));
@@ -59826,9 +59826,87 @@ var badgeText = (result3) => {
 };
 
 // src/challenge-commands.ts
+var challengeQuickstart = {
+  title: "Black Box quickstart",
+  goal: "Reverse-engineer the shipping price function, then submit a compatible JavaScript replacement.",
+  workflow: [
+    {
+      step: 1,
+      action: "Sign in",
+      command: "chofex login",
+      note: "Opens Clerk authentication in your browser."
+    },
+    {
+      step: 2,
+      action: "Check your budget",
+      command: "chofex challenge show",
+      note: "Shows remaining oracle queries and official evaluations."
+    },
+    {
+      step: 3,
+      action: "Probe the Black Box",
+      command: "chofex challenge query --distance 10 --weight 3 --hour 14 --fragile false --express false",
+      note: "A successful query reveals one shipping price and consumes one query."
+    },
+    {
+      step: 4,
+      action: "Study your observations",
+      command: "chofex challenge notebook",
+      note: "Compare inputs and outputs to infer the pricing rules."
+    },
+    {
+      step: 5,
+      action: "Build shipping.js",
+      file: "shipping.js",
+      source: [
+        "function calculateShipping(input) {",
+        "  // Return your predicted shipping price.",
+        "  return input.distanceKm + input.weightKg;",
+        "}"
+      ].join(`
+`),
+      note: "Define calculateShipping and return one finite number."
+    },
+    {
+      step: 6,
+      action: "Test your replacement safely",
+      command: "chofex challenge test --source ./shipping.js",
+      note: "Checks your solution against your notebook without consuming an official evaluation."
+    },
+    {
+      step: 7,
+      action: "Submit to the hidden test set",
+      command: "chofex challenge evaluate --source ./shipping.js",
+      note: "Official evaluations are limited. Use test as often as needed, then evaluate when your solution is ready."
+    },
+    {
+      step: 8,
+      action: "Check the leaderboard",
+      command: "chofex challenge ranking",
+      note: "Shows the public ranking without consuming budget."
+    }
+  ],
+  helpCommand: "chofex challenge query --help"
+};
+var challengeQuickstartText = () => {
+  const lines2 = [challengeQuickstart.title, challengeQuickstart.goal, ""];
+  for (const item of challengeQuickstart.workflow) {
+    lines2.push(`${item.step}. ${item.action}`);
+    if ("command" in item)
+      lines2.push(`   ${item.command}`);
+    if ("source" in item) {
+      lines2.push(...item.source.split(`
+`).map((line) => `   ${line}`));
+    }
+    lines2.push(`   ${item.note}`, "");
+  }
+  lines2.push(`More detail: ${challengeQuickstart.helpCommand}`);
+  return lines2.join(`
+`);
+};
 var optionalString = (name, description) => exports_Flag.string(name).pipe(exports_Flag.optional, exports_Flag.withDescription(description));
 var challengeFlag = exports_Flag.string("challenge").pipe(exports_Flag.withDefault(defaultChallengeSlug), exports_Flag.withDescription("Challenge slug (default: black-box)"));
-var sourceFlag = optionalString("source", "JavaScript file exporting function calculateShipping(input)");
+var sourceFlag = optionalString("source", "JavaScript file defining function calculateShipping(input)");
 var inputFlag = optionalString("input", "JSON file, or - for stdin");
 var formatFlag = exports_Flag.choice("format", ["table", "json", "csv"]).pipe(exports_Flag.withDefault("table"), exports_Flag.withDescription("Notebook format"));
 var numberFromOption = (value3) => {
@@ -59847,12 +59925,22 @@ var booleanFromOption = (value3) => {
 var listCommand = exports_Command.make("list", {}, exports_Effect.fn("challengeListCommand")(function* () {
   const options = yield* root;
   yield* execute(options.output, listChallenges({ apiUrl: options.apiUrl }), challengeListText);
-})).pipe(exports_Command.withDescription("List mini technical challenges"));
+})).pipe(exports_Command.withDescription("Discover available challenges, opening dates, and scoring formats. No login required."), exports_Command.withExamples([
+  {
+    command: "chofex challenge list",
+    description: "See which challenge is currently playable"
+  }
+]));
 var showCommand = exports_Command.make("show", { challenge: challengeFlag }, exports_Effect.fn("challengeShowCommand")(function* ({ challenge }) {
   const options = yield* root;
   const token = exports_Option.getOrUndefined(options.token);
   yield* execute(options.output, getChallengeAttempt({ apiUrl: options.apiUrl, token }, challenge), challengeShowText);
-})).pipe(exports_Command.withDescription("Show your Black Box status and remaining budget"));
+})).pipe(exports_Command.withDescription("Check your Black Box query budget, evaluation budget, score, and saved observations. Requires sign-in."), exports_Command.withExamples([
+  {
+    command: "chofex challenge show",
+    description: "Check your progress before spending limited attempts"
+  }
+]));
 var queryCommand = exports_Command.make("query", {
   challenge: challengeFlag,
   input: inputFlag,
@@ -59883,10 +59971,14 @@ var queryCommand = exports_Command.make("query", {
     return yield* queryChallenge({ apiUrl: options.apiUrl, token }, challenge, shipment);
   });
   yield* execute(options.output, operation, challengeQueryText);
-})).pipe(exports_Command.withDescription("Query the undocumented Black Box (uses one request)"), exports_Command.withExamples([
+})).pipe(exports_Command.withDescription("Send one shipment to the undocumented oracle. A successful query consumes one limited request. Requires sign-in."), exports_Command.withExamples([
   {
     command: "chofex challenge query --distance 10 --weight 3 --hour 14 --fragile false --express false",
     description: "Spend one oracle query"
+  },
+  {
+    command: "chofex challenge query --input shipment.json",
+    description: "Read the shipment fields from a JSON file"
   }
 ]));
 var notebookCommand = exports_Command.make("notebook", { challenge: challengeFlag, format: formatFlag }, exports_Effect.fn("challengeNotebookCommand")(function* ({ challenge, format: format6 }) {
@@ -59901,7 +59993,16 @@ var notebookCommand = exports_Command.make("notebook", { challenge: challengeFla
     }
     return notebookTableText(attempt.observations);
   });
-})).pipe(exports_Command.withDescription("Export Black Box observations as a table, JSON, or CSV"));
+})).pipe(exports_Command.withDescription("Review every input and price you observed. Export table, JSON, or CSV for analysis. Requires sign-in."), exports_Command.withExamples([
+  {
+    command: "chofex challenge notebook",
+    description: "Read observations in a terminal table"
+  },
+  {
+    command: "chofex challenge notebook --format csv > observations.csv",
+    description: "Save observations for a spreadsheet"
+  }
+]));
 var testCommand = exports_Command.make("test", { challenge: challengeFlag, source: sourceFlag }, exports_Effect.fn("challengeTestCommand")(function* ({ challenge, source }) {
   const options = yield* root;
   const token = exports_Option.getOrUndefined(options.token);
@@ -59910,7 +60011,12 @@ var testCommand = exports_Command.make("test", { challenge: challengeFlag, sourc
     return yield* testChallenge({ apiUrl: options.apiUrl, token }, challenge, solution);
   });
   yield* execute(options.output, operation, challengeTestText);
-})).pipe(exports_Command.withDescription("Test a replacement against your notebook without consuming an official evaluation"));
+})).pipe(exports_Command.withDescription("Check calculateShipping against your saved observations. Safe to repeat; official evaluations are not consumed. Requires sign-in."), exports_Command.withExamples([
+  {
+    command: "chofex challenge test --source ./shipping.js",
+    description: "Test a JavaScript replacement against your notebook"
+  }
+]));
 var evaluateCommand = exports_Command.make("evaluate", { challenge: challengeFlag, source: sourceFlag }, exports_Effect.fn("challengeEvaluateCommand")(function* ({ challenge, source }) {
   const options = yield* root;
   const token = exports_Option.getOrUndefined(options.token);
@@ -59919,12 +60025,47 @@ var evaluateCommand = exports_Command.make("evaluate", { challenge: challengeFla
     return yield* evaluateChallenge({ apiUrl: options.apiUrl, token }, challenge, solution);
   });
   yield* execute(options.output, operation, challengeEvaluateText);
-})).pipe(exports_Command.withDescription("Run an official hidden-set evaluation (limited attempts)"));
+})).pipe(exports_Command.withDescription("Score calculateShipping on hidden cases. This consumes one limited official evaluation. Requires sign-in."), exports_Command.withExamples([
+  {
+    command: "chofex challenge evaluate --source ./shipping.js",
+    description: "Spend one official evaluation when your solution is ready"
+  }
+]));
 var rankingCommand = exports_Command.make("ranking", { challenge: challengeFlag }, exports_Effect.fn("challengeRankingCommand")(function* ({ challenge }) {
   const options = yield* root;
   yield* execute(options.output, getChallengeRanking({ apiUrl: options.apiUrl }, challenge), challengeRankingText);
-})).pipe(exports_Command.withDescription("Show the public read-only challenge ranking"));
-var challengeCommand = exports_Command.make("challenge").pipe(exports_Command.withDescription("Play mini technical challenges and inspect public rankings"), exports_Command.withSubcommands([
+})).pipe(exports_Command.withDescription("View the public leaderboard. No login required and no challenge budget consumed."), exports_Command.withExamples([
+  {
+    command: "chofex challenge ranking",
+    description: "Compare official hidden-set scores"
+  }
+]));
+var challengeCommand = exports_Command.make("challenge", {}, exports_Effect.fn("challengeQuickstartCommand")(function* () {
+  const options = yield* root;
+  if (options.output === "json") {
+    yield* printJson({
+      version: 1,
+      ok: true,
+      requestId: crypto.randomUUID(),
+      data: challengeQuickstart
+    });
+    return;
+  }
+  yield* exports_Console.log(challengeQuickstartText());
+})).pipe(exports_Command.withDescription("Play mini technical challenges. Start here: learn the Black Box workflow from first query to leaderboard. Run without a subcommand for the guided quickstart."), exports_Command.withExamples([
+  {
+    command: "chofex challenge",
+    description: "Open the guided Black Box quickstart"
+  },
+  {
+    command: "chofex challenge query --distance 10 --weight 3 --hour 14 --fragile false --express false",
+    description: "Make your first oracle query"
+  },
+  {
+    command: "chofex challenge query --help",
+    description: "See flags and examples for the query step"
+  }
+]), exports_Command.withSubcommands([
   listCommand,
   showCommand,
   queryCommand,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chofex-cli",
-  "version": "0.1.78",
+  "version": "0.1.79",
   "description": "Command-line client for the Chofex Hackathon",
   "type": "module",
   "bin": {