Skip to content

Commit 54166a2

Browse files
committed
fix(cli): align build and command runtime surface
Refs #40
1 parent ae4f439 commit 54166a2

28 files changed

Lines changed: 810 additions & 267 deletions

‎CHANGELOG.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,13 @@ format: `Unreleased` then release buckets, grouped by impact.
2121
canonical decimal spelling across the interpreter, native C11, and Core
2222
Wasm lanes, allowing computed integers to be printed without handwritten
2323
digit tables.
24+
- Build target errors now use input- and toolchain-specific catalogs; scoped
25+
help and the CLI guide document the Web-compatible `wasm` alias, `-o` /
26+
`--output`, target and destination defaults, and structured `build --json`
27+
results. Profile Web collisions report Web-specific `SPX-I307`, concurrent
28+
project native builds have one create-new winner, and command-profile
29+
`run` output explains that it executes the entry while built adapters invoke
30+
the manifest command.
2431
- Single-file native and Web/Wasm builds now require fresh destinations.
2532
Native output is reserved before compiler invocation and Web output uses an
2633
atomic create-new directory, so existing sources/artifacts and concurrent

‎crates/semaprax-toolchain/tests/cli_help_surface_v1.rs‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,8 @@ const NEW_LINE: &str =
88
"semaprax new <destination> [--name project-name] [--template calculator|library]\n";
99
const PROJECT_SCAFFOLD_LINE: &str =
1010
"semaprax project-scaffold --name project-name [--template calculator|library] [--layout frozen|tables]\n";
11-
const BUILD_LINE: &str = "semaprax build [<file>|<dir>|semaprax.toml|--manifest-path path] [--target native|native-callable|web|wasm|npm|rust] [--profile internal-strings-v1] [--function stable-id] [--export stable-id ...] [-o path]\n";
11+
const BUILD_SOURCE_LINE: &str = "semaprax build <file> [--target native|native-callable|web|wasm] [--profile internal-strings-v1] [--function stable-id] [--export stable-id ...] [-o|--output path] [--json]\n";
12+
const BUILD_PROJECT_LINE: &str = "semaprax build [<dir>|semaprax.toml|--manifest-path path] [--target native|web|wasm|npm|rust] [-o|--output path] [--json]\n";
1213
const BANNER: &str = "SEMAPRAX — Meaning in. Verified machine code out.\n";
1314
const GUIDE_MAX_BYTES: usize = 2048;
1415

@@ -81,11 +82,12 @@ fn full_help_is_exact_capability_aware_and_inert() {
8182
assert_eq!(help.matches(DOCTOR_LINE).count(), 1);
8283
assert_eq!(help.matches(NEW_LINE).count(), 1);
8384
assert_eq!(help.matches(PROJECT_SCAFFOLD_LINE).count(), 1);
84-
assert_eq!(help.matches(BUILD_LINE).count(), 1);
85+
assert_eq!(help.matches(BUILD_SOURCE_LINE).count(), 1);
86+
assert_eq!(help.matches(BUILD_PROJECT_LINE).count(), 1);
8587
let doctor = help.find(DOCTOR_LINE).unwrap();
8688
let new = help.find(NEW_LINE).unwrap();
8789
let scaffold = help.find(PROJECT_SCAFFOLD_LINE).unwrap();
88-
let build = help.find(BUILD_LINE).unwrap();
90+
let build = help.find(BUILD_SOURCE_LINE).unwrap();
8991
assert!(doctor < new && new < scaffold && scaffold < build);
9092
std::fs::remove_dir(all_dir).unwrap();
9193

‎docs/CLI-GUIDE.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,23 @@ available build targets differ between the standalone and full toolchains.
119119
Commands that list `--json` in scoped help provide their structured form for
120120
automation.
121121

122+
`build` has separate target catalogs for its two input classes. A source file
123+
admits `native`, `native-callable`, `web`, and `wasm`; a project admits
124+
`native`, `web`, `wasm`, and `npm`, plus `rust` in the full toolchain. An
125+
unsupported-target diagnostic lists only the catalog the current input and
126+
toolchain can execute. `wasm` is an exact alias of `web`: both publish the
127+
same Web package directory, including `app.wasm`, rather than a bare Wasm
128+
file. `-o` and `--output` are equivalent.
129+
130+
When omitted, a source target defaults to `native` and its destination to
131+
`<source-stem>.out` beside the source. A project target defaults to `web`; its
132+
destination defaults inside the project root to `<name>-web` for `web` or
133+
`wasm`, `<name>-npm` for `npm`, `<name>-rust` for `rust`, and
134+
`<name>-out` plus the platform executable suffix for `native`. `build --json`
135+
prints one success object with `status`, `target`, `product`, and `output`
136+
(plus `manifest_sha256` for a native-callable bundle); build diagnostics use
137+
the ordinary one-diagnostic-per-line JSON form.
138+
122139
Every explicit single-file build output is create-new. Native builds reserve
123140
the exact destination before invoking the compiler and publish through that
124141
retained file; Web/Wasm builds atomically create a fresh package directory.
@@ -127,6 +144,11 @@ An existing file, directory, symlink, or concurrent winner is rejected with
127144
`SPX-I301`; builds never merge into an existing directory or overwrite their
128145
own `.spx` input.
129146

147+
For command-profile projects, `run` deliberately executes the project's
148+
ordinary entry rather than synthesizing process input for its command
149+
function. Human output includes a note naming both identities and points to
150+
the built native and Web/npm adapters that exercise the command function.
151+
130152
## Diagnose command-line errors
131153

132154
Command-line grammar errors exit without compiling the input. Start with

‎docs/CLI-HELP-V4.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -47,8 +47,10 @@ most 2048 bytes; that bound is a contract, enforced by unit and integration
4747
evidence, so the page stays one screen as commands are added.
4848

4949
Guided shapes are summaries, not grammar. The catalog's usage lines remain the
50-
single grammar authority: scoped help still renders them byte for byte, and a
51-
guided shape must not be parsed as an admission rule.
50+
single grammar authority: scoped help renders separate source and project
51+
`build` shapes so their target catalogs do not imply capabilities the input
52+
class lacks. Those shapes also expose `--json` and the `--output` spelling.
53+
A guided shape must not be parsed as an admission rule.
5254

5355
## Exhaustive catalog
5456

@@ -96,9 +98,9 @@ does not ship.
9698
## Preservation
9799

98100
Scoped help (`help <command>`, `<command> --help`, `<command> -h`), the
99-
malformed-position rejection, the recovery hint, command diagnostics, JSON
100-
formats, and side effects are unchanged. Help still calls no host hook, reads
101-
no path, inspects no environment, and grants no authority.
101+
malformed-position rejection, and the recovery hint are unchanged except for
102+
the additive `build` grammar described above. Help still calls no host hook,
103+
reads no path, inspects no environment, and grants no authority.
102104

103105
## Evidence
104106

‎docs/INSTALL.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -253,7 +253,7 @@ stdout. Invocation errors exit `2` and compiler or execution failures exit `1`.
253253
| ``unknown command `chekc`; did you mean `check`?`` | A misspelled command name. The suggestion compares only names already visible in that binary's catalog; see [capability-aware CLI typo guidance](CLI-HELP-V2.md). | Run the suggested name. |
254254
| `error[SPX-I001]: cannot read missing.spx: No such file or directory (os error 2)` | The source path does not exist, usually because the shell is in the wrong directory. | Check the working directory and the path. Paths are resolved relative to the process working directory. |
255255
| `error[SPX-J102]: cannot inspect declared Project v1 manifest <dir>/semaprax.toml: No such file or directory (os error 2)` | `check`, `run`, `test`, or `build` was given no input or a directory, and that directory holds no Project v1 manifest. A directory operand always means the `semaprax.toml` inside it. When no input was given, the diagnostic carries a `help:` line naming the admitted inputs. | Pass the `.spx` file, the project directory, or its `semaprax.toml`; from inside a project, `semaprax check .` works. See [Project Manifest v1](PROJECT-MANIFEST-V1.md). |
256-
| ``unsupported target `webb`; available: native, native-callable, web, wasm, npm`` | An unknown `--target` value. | Use one of the listed targets. |
256+
| ``unsupported target `webb`; available: native, native-callable, web, wasm`` | An unknown single-source `--target` value. | Use one of the listed targets; project and full-toolchain catalogs differ. |
257257
| `graph requires exactly <file>` | A required operand is missing. Every rejected known command appends a scoped-help hint; see [capability-aware CLI recovery](CLI-HELP-V3.md). | Run the hinted `semaprax <command> --help` for the exact accepted shape. |
258258
| `error[SPX-B101]: failed to start clang; install a C11 toolchain: No such file or directory (os error 2)` | The native lane could not spawn `clang`. | Install Clang and make sure it is on the `PATH` of the shell running the build. |
259259
| `project-scaffold requires --name project-name` | The scaffold capsule command was run without its required name. | Supply `--name`. See [Public Project Scaffold Capsule v1](PROJECT-SCAFFOLD-V1.md). |
@@ -272,7 +272,7 @@ hint: run `semaprax graph --help` for usage
272272
An unknown build target:
273273

274274
```text
275-
unsupported target `webb`; available: native, native-callable, web, wasm, npm
275+
unsupported target `webb`; available: native, native-callable, web, wasm
276276
hint: run `semaprax build --help` for usage
277277
```
278278

‎src/cli/build.rs‎

Lines changed: 46 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ pub(crate) struct BuildOptions {
1616
pub(crate) function: Option<String>,
1717
pub(crate) exports: Vec<String>,
1818
pub(crate) profile: Option<String>,
19+
pub(crate) json: bool,
1920
}
2021

2122
#[derive(Debug, Eq, PartialEq)]
@@ -46,6 +47,10 @@ pub(crate) struct ProjectOutputParent {
4647
/// Holding the exact destination file from before compilation through final
4748
/// publication prevents both accidental overwrite and two concurrent builds
4849
/// from claiming the same spelling.
50+
#[allow(
51+
dead_code,
52+
reason = "the quickstart parser harness includes this module without build execution"
53+
)]
4954
pub(crate) struct SourceNativeOutput {
5055
parent: PathBuf,
5156
parent_identity: Handle,
@@ -55,6 +60,10 @@ pub(crate) struct SourceNativeOutput {
5560
retained: bool,
5661
}
5762

63+
#[allow(
64+
dead_code,
65+
reason = "the quickstart parser harness includes this module without build execution"
66+
)]
5867
impl SourceNativeOutput {
5968
pub(crate) fn prepare(path: &Path) -> Result<Self, Diagnostic> {
6069
path.file_name().ok_or_else(|| {
@@ -428,14 +437,26 @@ pub(crate) fn bind_rust_output_parent(path: &Path) -> Result<PathBuf, Diagnostic
428437
}
429438
}
430439

440+
#[allow(
441+
dead_code,
442+
reason = "integration harnesses exercise the public capability class"
443+
)]
431444
pub(crate) fn parse(args: &[String]) -> Result<BuildOptions, u8> {
445+
parse_with_capabilities(args, false)
446+
}
447+
448+
pub(crate) fn parse_with_capabilities(
449+
args: &[String],
450+
private_toolchain: bool,
451+
) -> Result<BuildOptions, u8> {
432452
let mut input = None::<PathBuf>;
433453
let mut output = None::<PathBuf>;
434454
let mut manifest_path = None::<PathBuf>;
435455
let mut target = None::<String>;
436456
let mut function = None::<String>;
437457
let mut exports = Vec::<String>::new();
438458
let mut profile = None::<String>;
459+
let mut json = false;
439460
let mut index = 0;
440461
while index < args.len() {
441462
let argument = &args[index];
@@ -448,6 +469,15 @@ pub(crate) fn parse(args: &[String]) -> Result<BuildOptions, u8> {
448469
index += 1;
449470
continue;
450471
}
472+
if argument == "--json" {
473+
if json {
474+
eprintln!("build option `--json` may not be repeated");
475+
return Err(2);
476+
}
477+
json = true;
478+
index += 1;
479+
continue;
480+
}
451481
if matches!(
452482
argument.as_str(),
453483
"--target"
@@ -471,6 +501,7 @@ pub(crate) fn parse(args: &[String]) -> Result<BuildOptions, u8> {
471501
| "--manifest-path"
472502
| "-o"
473503
| "--output"
504+
| "--json"
474505
)
475506
|| !value.starts_with('-')
476507
})
@@ -525,7 +556,6 @@ pub(crate) fn parse(args: &[String]) -> Result<BuildOptions, u8> {
525556
"native".to_owned()
526557
}
527558
});
528-
let project_rust = matches!(&input, BuildInput::Project(_)) && target == "rust";
529559
if let Some(profile) = &profile {
530560
if profile != "internal-strings-v1"
531561
|| !matches!(&input, BuildInput::Source(_))
@@ -536,19 +566,12 @@ pub(crate) fn parse(args: &[String]) -> Result<BuildOptions, u8> {
536566
return Err(2);
537567
}
538568
}
539-
if !project_rust
540-
&& !matches!(
541-
target.as_str(),
542-
"native" | "native-callable" | "web" | "wasm" | "npm"
543-
)
544-
{
545-
if matches!(&input, BuildInput::Project(_)) {
546-
eprintln!("unsupported target `{target}`; available: native, web, wasm, npm, rust");
547-
} else {
548-
eprintln!(
549-
"unsupported target `{target}`; available: native, native-callable, web, wasm, npm"
550-
);
551-
}
569+
let available_targets = target_catalog(&input, private_toolchain);
570+
if !available_targets.contains(&target.as_str()) {
571+
eprintln!(
572+
"unsupported target `{target}`; available: {}",
573+
available_targets.join(", ")
574+
);
552575
return Err(2);
553576
}
554577
if target == "native-callable" {
@@ -564,10 +587,6 @@ pub(crate) fn parse(args: &[String]) -> Result<BuildOptions, u8> {
564587
eprintln!("--export is only valid with --target web or wasm");
565588
return Err(2);
566589
}
567-
if matches!(&input, BuildInput::Source(_)) && target == "npm" {
568-
eprintln!("npm is only valid with an authenticated Project v2 manifest");
569-
return Err(2);
570-
}
571590
if matches!(&input, BuildInput::Project(_)) {
572591
if !matches!(target.as_str(), "web" | "wasm" | "native" | "npm" | "rust") {
573592
eprintln!(
@@ -593,9 +612,18 @@ pub(crate) fn parse(args: &[String]) -> Result<BuildOptions, u8> {
593612
function,
594613
exports,
595614
profile,
615+
json,
596616
})
597617
}
598618

619+
fn target_catalog(input: &BuildInput, private_toolchain: bool) -> &'static [&'static str] {
620+
match (input, private_toolchain) {
621+
(BuildInput::Source(_), _) => &["native", "native-callable", "web", "wasm"],
622+
(BuildInput::Project(_), false) => &["native", "web", "wasm", "npm"],
623+
(BuildInput::Project(_), true) => &["native", "web", "wasm", "npm", "rust"],
624+
}
625+
}
626+
599627
#[cfg(test)]
600628
#[path = "build/tests.rs"]
601629
mod tests;

‎src/cli/build/tests.rs‎

Lines changed: 30 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -197,14 +197,17 @@ fn project_selectors_do_not_confuse_legacy_sources() {
197197
]))
198198
.is_err());
199199

200-
let rust = parse(&strings(&[
201-
"--manifest-path",
202-
"fixtures/semaprax.toml",
203-
"--target",
204-
"rust",
205-
"-o",
206-
"sdk",
207-
]))
200+
let rust = parse_with_capabilities(
201+
&strings(&[
202+
"--manifest-path",
203+
"fixtures/semaprax.toml",
204+
"--target",
205+
"rust",
206+
"-o",
207+
"sdk",
208+
]),
209+
true,
210+
)
208211
.unwrap();
209212
assert_eq!(rust.target, "rust");
210213
assert_eq!(rust.output, Some(PathBuf::from("sdk")));
@@ -225,6 +228,25 @@ fn project_selectors_do_not_confuse_legacy_sources() {
225228
assert!(absolute_rust_output(Path::new("dist/../rust")).is_err());
226229
}
227230

231+
#[test]
232+
fn json_and_capability_selected_target_catalogs_are_explicit() {
233+
let source = parse(&strings(&["app.spx", "--json"])).unwrap();
234+
assert!(source.json);
235+
assert_eq!(source.target, "native");
236+
assert!(parse(&strings(&[
237+
"semaprax.toml",
238+
"--target",
239+
"native-callable",
240+
"--function",
241+
"app.main",
242+
]))
243+
.is_err());
244+
assert!(parse(&strings(&["semaprax.toml", "--target", "rust"])).is_err());
245+
assert!(
246+
parse_with_capabilities(&strings(&["semaprax.toml", "--target", "rust"]), true,).is_ok()
247+
);
248+
}
249+
228250
#[test]
229251
fn rust_output_binds_the_existing_parent_canonical_spelling() {
230252
let current = std::env::current_dir().unwrap();

‎src/cli/help.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -163,7 +163,7 @@ static COMMANDS: &[CommandSpec] = &[
163163
CommandSpec { id: CommandId::Doctor, canonical: "doctor", aliases: &[], availability: Availability::Private, global: true, usages: &["semaprax doctor [--profile <id>] [--target native|web|all] [--json]"] },
164164
CommandSpec { id: CommandId::New, canonical: "new", aliases: &[], availability: Availability::Public, global: true, usages: &["semaprax new <destination> [--name project-name] [--template calculator|library]"] },
165165
CommandSpec { id: CommandId::ProjectScaffold, canonical: "project-scaffold", aliases: &[], availability: Availability::Public, global: true, usages: &["semaprax project-scaffold --name project-name [--template calculator|library] [--layout frozen|tables]"] },
166-
CommandSpec { id: CommandId::Build, canonical: "build", aliases: &[], availability: Availability::Public, global: true, usages: &["semaprax build [<file>|<dir>|semaprax.toml|--manifest-path path] [--target native|native-callable|web|wasm|npm|rust] [--profile internal-strings-v1] [--function stable-id] [--export stable-id ...] [-o path]"] },
166+
CommandSpec { id: CommandId::Build, canonical: "build", aliases: &[], availability: Availability::Public, global: true, usages: &["semaprax build <file> [--target native|native-callable|web|wasm] [--profile internal-strings-v1] [--function stable-id] [--export stable-id ...] [-o|--output path] [--json]", "semaprax build [<dir>|semaprax.toml|--manifest-path path] [--target native|web|wasm|npm|rust] [-o|--output path] [--json]"] },
167167
CommandSpec { id: CommandId::Run, canonical: "run", aliases: &[], availability: Availability::Public, global: true, usages: &["semaprax run <file> [--json] [--max-steps N] [--max-bytes N] [--native]", "semaprax run [<dir>|semaprax.toml|--manifest-path path] [--json] [--max-steps N] [--max-bytes N]"] },
168168
CommandSpec { id: CommandId::Test, canonical: "test", aliases: &[], availability: Availability::Public, global: true, usages: &["semaprax test [<dir>|semaprax.toml|--manifest-path path] [--json] [--max-steps N] [--max-bytes N]"] },
169169
CommandSpec { id: CommandId::Fmt, canonical: "fmt", aliases: &[], availability: Availability::Public, global: true, usages: &["semaprax fmt <file>|<dir>|semaprax.toml [--check]"] },

0 commit comments

Comments
 (0)