diff --git a/Cargo.lock b/Cargo.lock index a475148c0..6f013f2b6 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -14049,7 +14049,6 @@ dependencies = [ "dunce", "raea-app-check", "raea-app-registry", - "raea-core-brief", "raea-core-facts", "raea-io-assets", "raea-io-home", diff --git a/apps/check/src/lib.rs b/apps/check/src/lib.rs index c7f3577f5..39430e662 100644 --- a/apps/check/src/lib.rs +++ b/apps/check/src/lib.rs @@ -83,9 +83,10 @@ struct Taste { line: String, } -/// The checks among a person's taste rules (taste.ts and its kinds), each with the line it stands for. +/// The checks among a person's taste rules (taste.ts and its kinds) that a video alone shows (the six forms), each +/// with the line it stands for. fn taste_rules(tastes: &[raea_core_brief::Taste]) -> Vec { - tastes.iter().flat_map(|t| &t.sections).flat_map(|s| &s.rules).filter_map(|r| r.check.map(|c| Taste { form: c.form(), value: c.value(), line: r.text.clone() })).collect() + tastes.iter().flat_map(|t| t.checks()).map(|(line, c)| Taste { form: c.form(), value: c.value(), line: line.to_string() }).collect() } fn taste_of<'a>(rules: &'a [Taste], form: &str) -> Option<&'a Taste> { diff --git a/apps/direction/Cargo.toml b/apps/direction/Cargo.toml index e038d3c12..94f69c2b4 100644 --- a/apps/direction/Cargo.toml +++ b/apps/direction/Cargo.toml @@ -15,7 +15,7 @@ raea-core-facts = { path = "../../core/facts" } # a render's record named by when it was (UTC) raea-io-trace = { path = "../../io/trace" } serde_json = "1" -# `raea check PROJECT | EDIT.tsx` (DR4): taste and controllers' rules, the floor on a composition's newest render, the +# `raea check PROJECT | EDIT.tsx` (DR4): the taste files' rules, the floor on a composition's newest render, the # project's compositions raea-core-brief = { path = "../../core/brief" } raea-app-check = { path = "../check" } diff --git a/apps/direction/src/check.rs b/apps/direction/src/check.rs index 6cc40020e..05489dd10 100644 --- a/apps/direction/src/check.rs +++ b/apps/direction/src/check.rs @@ -1,13 +1,13 @@ //! `raea check PROJECT|EDIT.tsx` (docs/direction.feature DR4): every check that applies, run over each -//! composition's worlds. The rules come from raea's floor, the person's taste (and the workspace's), and the -//! workspace's and the project's controllers; each is one of raea's named checks (systems.rs) or a project's TS check -//! (ts.rs), and where it was written changes nothing about how it runs. A check that needs a render runs on the +//! composition's worlds. The rules come from raea's floor and the taste files: the person's, the workspace's and the +//! project's; each is one of raea's named checks (systems.rs) or a project's TS check (ts.rs), and where it was +//! written changes nothing about how it runs. A check that needs a render runs on the //! composition's newest render; with none, it waits, and the command says what for. `raea check VIDEO.mp4` is the //! floor alone (apps/check). use std::path::{Path, PathBuf}; -use raea_core_brief::{controller, taste}; +use raea_core_brief::taste; use raea_core_facts::{finding, record, Facts, Finding, Level, Rule, Shot}; use raea_runtime_bundle::flag; use raea_runtime_world::{Ask, Render}; @@ -18,7 +18,7 @@ use crate::ts; type R = Result; -pub const USAGE: &str = "raea check [PROJECT|EDIT.tsx] [--composition ID] [--only ID] [--taste T] [--render OUT | --no-render] [--json] (every check that applies to each composition, over its frames: raea's floor on its newest render, the person's taste, the workspace's and the project's rules (a controller's rule fields: one of raea's checks by name, or a project's .ts check); what needs a render and has none waits, and says so)"; +pub const USAGE: &str = "raea check [PROJECT|EDIT.tsx] [--composition ID] [--only ID] [--taste T] [--render OUT | --no-render] [--json] (every check that applies to each composition, over its frames: raea's floor on its newest render, the person's, the workspace's and the project's taste.ts (each line's check: one of raea's forms or checks by name, or a project's .ts check); what needs a render and has none waits, and says so)"; /// The flags raea check takes with a value (its own, and the floor's on a video). const TAKES: [&str; 10] = ["--composition", "--only", "--taste", "--render", "--manifest", "--words", "--perception", "--shape", "--platform", "-o"]; @@ -71,7 +71,12 @@ fn tastes(project: &Path, given: Vec, host: &Host) -> Vec { } } } - out.extend(record::up(project, ".raea/workspace").map(|ws| ws.join("taste.ts")).filter(|f| f.is_file())); + // the workspace's, then the project's own (the same file when the project is the workspace's folder) + for f in record::up(project, ".raea/workspace").map(|ws| ws.join("taste.ts")).into_iter().chain([project.join("taste.ts")]) { + if f.is_file() && !out.contains(&f) { + out.push(f); + } + } out } @@ -98,8 +103,8 @@ fn rules(project: &Path, given: Vec, host: &Host) -> (Vec, Vec, host: &Host) -> (Vec, Vec) { // raea's own: the floor, and the reading check (DR28: its findings keep their own levels, so no rule level) let read = Rule { level: None, ..Rule::named("text-read", "text can be read for as long as it needs, and OCR reads it", Default::default(), Level::Warn, "raea") }; @@ -107,26 +112,12 @@ fn held(project: &Path, given: Vec, host: &Host) -> (Vec, Vec(&name(&f), &j)) { - Ok(t) => out.extend(t.sections.iter().flat_map(|s| &s.rules).filter_map(|r| Some(Rule::of_taste(&r.text, r.check?, &name(&f))))), + Ok(t) => out.extend(t.sections.iter().flat_map(|s| &s.rules).filter_map(|r| Rule::of_taste(r, &dir, &by))), Err(e) => bad.push(Finding::new("taste", Level::Error, format!("raea can't read it: {e}"), "raea check").about(name(&f), None)), } } - let ws = record::up(project, ".raea/workspace"); - for (dir, scope) in ws.iter().map(|w| (raea_app_registry::shared_dir(w, "controllers"), "workspace")).chain([(project.join("controllers"), "project")]) { - // a workspace's own folder is its project's too: read once - if scope == "project" && ws.as_deref() == Some(project) { - continue; - } - let mut files: Vec = std::fs::read_dir(&dir).into_iter().flatten().flatten().map(|e| e.path()).filter(|p| p.extension().is_some_and(|x| x == "ts")).collect(); - files.sort(); - for f in files { - match (host.ts.eval)(&f).and_then(|j| controller::of_json(&j)) { - Ok(c) => out.extend(Rule::of_controller(&c, &dir, &format!("{scope} {}", name(&f)))), - Err(e) => bad.push(Finding::new("controller", Level::Error, format!("raea can't read it: {e}"), "raea check").about(name(&f), None)), - } - } - } (out, bad) } @@ -134,7 +125,7 @@ fn held(project: &Path, given: Vec, host: &Host) -> (Vec, Vec R)>> { let one = flag(args, "--composition"); let (dir, file) = if target.is_dir() { (target.to_path_buf(), None) } else { (target.parent().unwrap_or(Path::new(".")).to_path_buf(), Some(dunce::canonicalize(&target).map_err(|e| format!("{}: {e}", target.display()))?)) }; - let reg = raea_app_registry::scan(&dir, &[]); + let reg = raea_app_registry::scan(&dir); let mut out: Vec<(PathBuf, Option)> = Vec::new(); for c in ®.compositions { let path = reg.dir.join(&c.file); diff --git a/apps/direction/src/systems/tests.rs b/apps/direction/src/systems/tests.rs index b3efd8fd4..c8231205f 100644 --- a/apps/direction/src/systems/tests.rs +++ b/apps/direction/src/systems/tests.rs @@ -53,7 +53,7 @@ fn placement_and_margin_name_the_worst_frame_of_a_run() { #[test] fn a_rule_with_no_value_says_so() { - let r = Rule { level: Some(Level::Warn), ..Rule::named("text-hold", "", Map::new(), Level::Error, "project controllers/rules.ts") }; + let r = Rule { level: Some(Level::Warn), ..Rule::named("text-hold", "", Map::new(), Level::Error, "taste taste.ts") }; let got = text(&r, &piece(3, |_| vec![])); assert_eq!((got.len(), got[0].level), (1, Level::Warn)); assert!(got[0].says.contains("needs a value")); diff --git a/apps/notes/src/check.rs b/apps/notes/src/check.rs index f00f1a058..03def3c59 100644 --- a/apps/notes/src/check.rs +++ b/apps/notes/src/check.rs @@ -63,7 +63,7 @@ fn numbered<'a>(project: &Path, notes: &'a [Kept]) -> Vec<(u32, &'a Kept, &'a ra } /// The notes' asks that have a check, each as a rule: the ask's id (n3.2) and words, its check (a .ts check's path -/// from the note's folder, as a controller's is from its own), its values, `by` the ask; and each note that can't be +/// from the note's folder, as a taste line's is from its file's), its values, `by` the ask; and each note that can't be /// read, as a finding. pub fn rules(project: &Path, notes: &[Kept]) -> (Vec, Vec) { let bad = notes.iter().filter_map(|k| k.note.as_ref().err().map(|e| Finding::new("note", Level::Error, format!("raea can't read it: {e}"), "raea notes").about(k.file.display().to_string(), None))).collect(); diff --git a/apps/workspace/Cargo.toml b/apps/workspace/Cargo.toml index e61be5e60..c6fd6aaf7 100644 --- a/apps/workspace/Cargo.toml +++ b/apps/workspace/Cargo.toml @@ -4,17 +4,15 @@ version = "0.1.0" edition = "2024" license = "FSL-1.1-ALv2" publish = false -description = "`raea workspace`, `raea project` and `raea controller`: a workspace's folders, projects and controllers, each change a commit" +description = "`raea workspace` and `raea project`: a workspace's folders and projects, each change a commit" [dependencies] dunce = "1" -# the controller schema (core/brief controller.rs): a controller file is checked and normalized against it -raea-core-brief = { path = "../../core/brief" } raea-io-home = { path = "../../io/home" } # git, which a workspace is: the PATH's, else on Windows the app's or raea's own (raea_io_assets::git) raea-io-assets = { path = "../../io/assets" } serde_json = "1" -# a project's compositions, components and controllers read from their source (docs/projects.feature PJ8) +# a project's compositions and components read from their source (docs/projects.feature PJ8) raea-app-registry = { path = "registry" } # the project's record of what renders and checks found, which raea next reads (docs/direction.feature DR3) raea-core-facts = { path = "../../core/facts" } diff --git a/apps/workspace/registry/Cargo.toml b/apps/workspace/registry/Cargo.toml index 7045b5b2a..3e8475860 100644 --- a/apps/workspace/registry/Cargo.toml +++ b/apps/workspace/registry/Cargo.toml @@ -4,7 +4,7 @@ version = "0.1.0" edition = "2024" license = "FSL-1.1-ALv2" publish = false -description = "A raea project's compositions, components and controllers, read from their source without running it, and lint for what isn't connected (docs/projects.feature PJ8)" +description = "A raea project's compositions and components, read from their source without running it, and lint for what isn't connected (docs/projects.feature PJ8)" [dependencies] dunce = "1" diff --git a/apps/workspace/registry/src/lib.rs b/apps/workspace/registry/src/lib.rs index 18e907726..1406602e5 100644 --- a/apps/workspace/registry/src/lib.rs +++ b/apps/workspace/registry/src/lib.rs @@ -1,13 +1,11 @@ -//! A project's compositions, components and controllers, registered by reading its files (docs/projects.feature PJ8), +//! A project's compositions and components, registered by reading its files (docs/projects.feature PJ8), //! so the raea app, `raea project scan`, `raea doctor` and `raea next` agree on what each file is: //! - a composition is each a registerRoot registers (its props read from the source, not rendered), or a //! .tsx's default export with none that no other file imports, registered for it under its file's name (versions //! NAME-vN.tsx are one composition), sized from its newest render's manifest when it has one; -//! - a component is a .tsx a composition imports, directly or through another; -//! - a controller is a module whose default export is `controller({...})` from "raea/brief". -//! What isn't connected is linted (lint.rs), each with its file and line and the fix. raea-app-workspace wraps `scan` -//! with the project's controller overrides (read from .raea/project's git config) and runs it for `raea project scan`, -//! `raea doctor`, `raea next` and `raea context`. +//! - a component is a .tsx a composition imports, directly or through another. +//! What isn't connected is linted (lint.rs), each with its file and line and the fix. raea-app-workspace runs `scan` +//! for `raea project scan`, `raea doctor`, `raea next` and `raea context`. use std::collections::{BTreeMap, BTreeSet}; use std::path::{Path, PathBuf}; @@ -22,9 +20,9 @@ pub use read::{Facts, Prop}; /// The nearest folder at or above a path that holds a marker (.raea/workspace, .raea/project), as the record finds it. pub use raea_core_facts::record::up; -/// The workspace's shared folder of one kind (docs/layout.feature: shared/compositions, components, controllers, assets, -/// artifacts), which every project can call on as @shared//. A workspace from before shared/ keeps that kind at -/// its root (controllers/, artifacts/) until `raea workspace tidy` moves it, and it's read there meanwhile. +/// The workspace's shared folder of one kind (docs/layout.feature: shared/compositions, components, assets, artifacts), +/// which every project can call on as @shared//. A workspace from before shared/ keeps that kind at its root +/// (artifacts/) until `raea workspace tidy` moves it, and it's read there meanwhile. pub fn shared_dir(ws: &Path, kind: &str) -> PathBuf { let old = ws.join(kind); if !ws.join("shared").is_dir() && old.is_dir() { @@ -33,7 +31,7 @@ pub fn shared_dir(ws: &Path, kind: &str) -> PathBuf { ws.join("shared").join(kind) } -/// A name as a folder: lowercase, dashes. A controller's id from its title is this (core/brief fills it the same way). +/// A name as a folder: lowercase, dashes. pub fn slug(s: &str) -> String { let mut out = String::new(); for c in s.trim().to_lowercase().chars() { @@ -82,13 +80,6 @@ pub struct Component { pub used_by: Vec, } -#[derive(Debug, Clone)] -pub struct Controller { - pub id: Option, - pub file: String, - pub line: usize, -} - #[derive(Debug)] pub struct Registry { pub dir: PathBuf, @@ -96,7 +87,6 @@ pub struct Registry { pub project: bool, pub compositions: Vec, pub components: Vec, - pub controllers: Vec, pub lint: Vec, } @@ -180,9 +170,8 @@ fn manifest(path: &Path) -> Option { serde_json::from_str(&std::fs::read_to_string(f).ok()?).ok() } -/// The folder's registry. `overridden`: the controller ids the project's overrides name, each checked against the -/// controllers there (the folder's and its workspace's controllers/). -pub fn scan(dir: &Path, overridden: &[String]) -> Registry { +/// The folder's registry. +pub fn scan(dir: &Path) -> Registry { let dir = dunce::canonicalize(dir).unwrap_or_else(|_| dir.to_path_buf()); let project = up(&dir, ".raea/project").is_some(); let mut found = Vec::new(); @@ -243,10 +232,9 @@ pub fn scan(dir: &Path, overridden: &[String]) -> Registry { .filter(|f| f.rel.ends_with(".tsx") && !comp_files.contains(f.rel.as_str()) && used_by.contains_key(&f.rel)) .map(|f| Component { file: f.rel.clone(), used_by: used_by[&f.rel].iter().cloned().collect() }) .collect(); - let controllers = files.iter().filter_map(|f| f.facts.controller.as_ref().map(|c| Controller { id: c.id.clone(), file: f.rel.clone(), line: c.line })).collect(); - let mut reg = Registry { dir, project, compositions, components, controllers, lint: Vec::new() }; - reg.lint = lint::lint(®, &files, &used_by, overridden); + let mut reg = Registry { dir, project, compositions, components, lint: Vec::new() }; + reg.lint = lint::lint(®, &files, &used_by); reg } @@ -280,13 +268,12 @@ impl Registry { "component": c.component, "width": p(&c.width), "height": p(&c.height), "fps": p(&c.fps), "frames": p(&c.frames), })).collect::>(), "components": self.components.iter().map(|c| json!({ "file": c.file, "usedBy": c.used_by })).collect::>(), - "controllers": self.controllers.iter().map(|c| json!({ "id": c.id, "file": c.file, "line": c.line })).collect::>(), "findings": self.lint.iter().map(Lint::finding).collect::>(), }) } - /// For an agent (`raea context`): each composition with its id, file, size, fps and length, the components and - /// controllers, and what isn't connected (its warnings, at most ten; the notes are `raea project scan`'s). + /// For an agent (`raea context`): each composition with its id, file, size, fps and length, the components, and + /// what isn't connected (its warnings, at most ten; the notes are `raea project scan`'s). pub fn summary(&self) -> String { let p = |v: &Option| match v { Some(Prop::Num(n)) => format!("{n}"), @@ -304,9 +291,6 @@ impl Registry { if !self.components.is_empty() { out.push_str(&format!("components: {}\n", self.components.iter().map(|c| c.file.as_str()).collect::>().join(", "))); } - if !self.controllers.is_empty() { - out.push_str(&format!("controllers: {}\n", self.controllers.iter().map(|c| format!("{} ({})", c.id.as_deref().unwrap_or("?"), c.file)).collect::>().join(", "))); - } let warn: Vec<&Lint> = self.warnings().collect(); if !warn.is_empty() { out.push_str(&format!("\nnot connected ({}; raea doctor --fix fixes what it can):\n", warn.len())); @@ -321,11 +305,10 @@ impl Registry { /// each about its file:line with the fix, and their count last. pub fn text(&self) -> String { let mut out = format!( - "{}: {} compositions, {} components, {} controllers", + "{}: {} compositions, {} components", self.dir.display(), self.compositions.len(), - self.components.len(), - self.controllers.len() + self.components.len() ); for c in &self.compositions { out.push_str(&format!("\n composition {} ({}:{}{})", c.id, c.file, c.line, if c.how == How::Default { ", its default export" } else { "" })); diff --git a/apps/workspace/registry/src/lint.rs b/apps/workspace/registry/src/lint.rs index 9099ab154..46ebb9d4f 100644 --- a/apps/workspace/registry/src/lint.rs +++ b/apps/workspace/registry/src/lint.rs @@ -20,8 +20,6 @@ pub enum Level { pub enum Fix { /// registers a default export: an import line at the top (when one is missing) and a registerRoot at the end Register { file: PathBuf, import: Option, root: String }, - /// a controller moved to the workspace's (or the project's) controllers/ - Move { from: PathBuf, to: PathBuf }, } #[derive(Debug, Clone)] @@ -66,13 +64,12 @@ fn warn(file: &str, line: usize, rule: &'static str, says: String, fix: impl Int Lint { file: file.into(), line, rule, level: Level::Warn, says, fix: fix.into(), action: None } } -pub(super) fn lint(reg: &Registry, files: &[File], used_by: &BTreeMap>, overridden: &[String]) -> Vec { +pub(super) fn lint(reg: &Registry, files: &[File], used_by: &BTreeMap>) -> Vec { let mut out = Vec::new(); - if !reg.project && !(reg.compositions.is_empty() && reg.controllers.is_empty()) { + if !reg.project && !reg.compositions.is_empty() { out.push(warn("", 0, "not-a-project", "this folder isn't in a raea project (no .raea/project at or above it)".into(), "raea project new NAME and move the files in, or raea workspace adopt the folder")); } let comp_files: BTreeSet<&str> = reg.compositions.iter().map(|c| c.file.as_str()).collect(); - let controller_files: BTreeSet<&str> = reg.controllers.iter().map(|c| c.file.as_str()).collect(); // the workspace's shared/, which a project reaches as @shared/ let shared = super::up(®.dir, ".raea/workspace").map(|w| { let s = w.join("shared"); @@ -89,7 +86,7 @@ pub(super) fn lint(reg: &Registry, files: &[File], used_by: &BTreeMaps), so its compositions aren't listed".into(), fix: "known when it renders; write each inside registerRoot to have them listed before".into(), action: None }); } // a .tsx that is neither a composition nor reached from one - if f.rel.ends_with(".tsx") && !f.facts.roots && !comp_files.contains(f.rel.as_str()) && !used_by.contains_key(&f.rel) && !controller_files.contains(f.rel.as_str()) { + if f.rel.ends_with(".tsx") && !f.facts.roots && !comp_files.contains(f.rel.as_str()) && !used_by.contains_key(&f.rel) { out.push(warn(&f.rel, 1, "orphan", "isn't a composition, and no composition imports it".into(), "register it (a default export or a registerRoot ), import it from a composition, or delete it")); } for (spec, line) in f.facts.imports.iter().filter(|(s, _)| is_path(s)) { @@ -197,54 +194,6 @@ pub(super) fn lint(reg: &Registry, files: &[File], used_by: &BTreeMap reg.dir.join("controllers"), - Some(w) => super::shared_dir(w, "controllers"), - None => reg.dir.join("controllers"), - }; - let mut ids: BTreeMap> = BTreeMap::new(); - for c in ®.controllers { - let f = files.iter().find(|f| f.rel == c.file).expect("a controller's file was read"); - if let Some(id) = &c.id { - ids.entry(id.clone()).or_default().push(&c.file); - } - let in_home = f.path.parent().and_then(Path::file_name).is_some_and(|n| n == "controllers"); - if !in_home { - let id = c.id.clone().unwrap_or_else(|| stem(&c.file)); - let to = home.join(format!("{id}.ts")); - out.push(Lint { - file: c.file.clone(), - line: c.line, - rule: "controller-home", - level: Level::Warn, - says: "a controller outside controllers/: `raea controller` and the app don't read it".into(), - fix: format!("move it to {}", to.display()), - action: (!to.exists()).then(|| Fix::Move { from: f.path.clone(), to }), - }); - } - } - for (id, at) in ids.iter().filter(|(_, at)| at.len() > 1) { - for f in at { - out.push(warn(f, 1, "controller-duplicate", format!("controller \"{id}\" is declared in {} files", at.len()), "keep one: the others' fields override nothing")); - } - } - // the workspace's controllers too, read the same way, for overrides naming them - let mut known: BTreeSet = ids.keys().cloned().collect(); - for e in std::fs::read_dir(&home).into_iter().flatten().flatten() { - let src = std::fs::read_to_string(e.path()).unwrap_or_default(); - if let Some(id) = super::read::read(&src, false).controller.and_then(|c| c.id) { - known.insert(id); - } - } - let mut named = BTreeSet::new(); - for id in overridden { - if !known.contains(id) && named.insert(id.clone()) { - out.push(warn(".raea/project", 0, "override-missing", format!("overrides controller \"{id}\", which isn't there"), format!("raea controller ls lists the ones there; remove the override with git config --file .raea/project --remove-section controller.{id}"))); - } - } out } @@ -257,12 +206,5 @@ pub fn apply(fix: &Fix) -> Result { std::fs::write(file, text).map_err(|e| format!("{}: {e}", file.display()))?; Ok(format!("registered {}", file.display())) } - Fix::Move { from, to } => { - if let Some(d) = to.parent() { - std::fs::create_dir_all(d).map_err(|e| e.to_string())?; - } - std::fs::rename(from, to).map_err(|e| format!("{}: {e}", from.display()))?; - Ok(format!("moved {} to {}", from.display(), to.display())) - } } } diff --git a/apps/workspace/registry/src/read.rs b/apps/workspace/registry/src/read.rs index d6064fc70..7bc91863b 100644 --- a/apps/workspace/registry/src/read.rs +++ b/apps/workspace/registry/src/read.rs @@ -1,8 +1,7 @@ //! What one .tsx or .ts file declares, read from its source without running it (docs/projects.feature PJ8): the //! compositions its registerRoot registers, each 's id, component, size, fps and length (a value written -//! out, or the expression that computes it); its default export; what it imports; and whether its default export is a -//! controller (`export default controller({...})` from "raea/brief"). A prop written as a top-level constant, or simple -//! arithmetic on them (`const FPS = 30; … durationInFrames={15 * FPS}`), is read as its value. +//! out, or the expression that computes it); its default export; and what it imports. A prop written as a top-level +//! constant, or simple arithmetic on them (`const FPS = 30; … durationInFrames={15 * FPS}`), is read as its value. use oxc::allocator::Allocator; use oxc::ast::ast::*; use oxc::ast_visit::{Visit, walk}; @@ -43,13 +42,6 @@ pub struct Registered { pub frames: Option, } -/// A controller the file's default export declares: its id (written, else from its title), at a line. -#[derive(Debug, Clone)] -pub struct Declared { - pub line: usize, - pub id: Option, -} - #[derive(Debug, Default)] pub struct Facts { pub registered: Vec, @@ -57,7 +49,6 @@ pub struct Facts { pub default: Option>, /// each import or re-export's module, at its line pub imports: Vec<(String, usize)>, - pub controller: Option, /// the names it imports from "raea" (a fix that registers its default export adds only what's missing) pub raea_names: Vec, /// why it didn't parse (the first diagnostic), when it didn't @@ -78,7 +69,6 @@ pub fn read(source: &str, tsx: bool) -> Facts { f.broken = Some(d.to_string()); return f; } - let mut controller_fn = None; for s in &parsed.program.body { match s { Statement::ImportDeclaration(d) => { @@ -86,15 +76,6 @@ pub fn read(source: &str, tsx: bool) -> Facts { if d.source.value == "raea" { f.raea_names.extend(d.specifiers.iter().flatten().map(|sp| sp.local().name.to_string())); } - if d.source.value == "raea/brief" { - for sp in d.specifiers.iter().flatten() { - if let ImportDeclarationSpecifier::ImportSpecifier(x) = sp - && x.imported.name() == "controller" - { - controller_fn = Some(sp.local().name.to_string()); - } - } - } } Statement::ExportFromDeclaration(d) => f.imports.push((d.source.value.to_string(), line(d.span.start))), Statement::ExportAllDeclaration(d) => f.imports.push((d.source.value.to_string(), line(d.span.start))), @@ -110,12 +91,6 @@ pub fn read(source: &str, tsx: bool) -> Facts { ExportDefaultDeclarationKind::Identifier(x) => Some(x.name.to_string()), _ => None, }); - if let ExportDefaultDeclarationKind::CallExpression(c) = &d.declaration - && let Expression::Identifier(callee) = &c.callee - && controller_fn.as_deref() == Some(callee.name.as_str()) - { - f.controller = Some(Declared { line: line(d.span.start), id: controller_id(c) }); - } } _ => {} } @@ -130,21 +105,6 @@ pub fn read(source: &str, tsx: bool) -> Facts { f } -/// A controller's id as written, else from its title (core/brief fills an id in from the title the same way). -fn controller_id(c: &CallExpression) -> Option { - let Some(Argument::ObjectExpression(o)) = c.arguments.first() else { return None }; - let text = |key: &str| { - o.properties.iter().find_map(|p| match p { - ObjectPropertyKind::ObjectProperty(p) if p.key.static_name().as_deref() == Some(key) => match &p.value { - Expression::StringLiteral(s) => Some(s.value.to_string()), - _ => None, - }, - _ => None, - }) - }; - text("id").or_else(|| text("title").map(|t| super::slug(&t))) -} - /// The file's top-level numeric constants, in order: `const FPS = 30`, `const DUR = 15 * FPS`, and an object constant's /// numeric properties as `NAME.prop` (`const edit = { fps: 30 }`). fn consts(p: &Program) -> HashMap { diff --git a/apps/workspace/registry/src/tests.rs b/apps/workspace/registry/src/tests.rs index 76514efed..e1e2f3381 100644 --- a/apps/workspace/registry/src/tests.rs +++ b/apps/workspace/registry/src/tests.rs @@ -1,4 +1,4 @@ -//! PJ8: a project's files read as compositions, components and controllers, and what isn't connected linted. +//! PJ8: a project's files read as compositions and components, and what isn't connected linted. use super::*; fn project() -> (tempdir::Dir, PathBuf) { @@ -21,8 +21,6 @@ fn project() -> (tempdir::Dir, PathBuf) { w("bare.render.json", "{\"width\": 1080, \"height\": 1080, \"fps\": 30, \"frames\": [{}, {}, {}]}"); w("anon.tsx", "export default () =>
;\n"); w("broken.tsx", "export default function (\n"); - w("controllers/delivery.ts", "import { controller } from \"raea/brief\";\nexport default controller({ id: \"delivery\", title: \"Delivery\", groups: [] });\n"); - w("settings/look.ts", "import { controller } from \"raea/brief\";\n\nexport default controller({ title: \"Look and feel\", groups: [] });\n"); std::fs::write(t.0.join("outside.tsx"), "export const far = 1;\n").unwrap(); (t, p) } @@ -46,9 +44,9 @@ mod tempdir { } #[test] -fn compositions_components_and_controllers_are_read_from_the_files() { +fn compositions_and_components_are_read_from_the_files() { let (_t, p) = project(); - let r = scan(&p, &[]); + let r = scan(&p); assert!(r.project); let comps: Vec<(&str, &str, How)> = r.compositions.iter().map(|c| (c.id.as_str(), c.file.as_str(), c.how)).collect(); assert!(comps.contains(&("promo", "promo.tsx", How::Registered))); @@ -65,14 +63,12 @@ fn compositions_components_and_controllers_are_read_from_the_files() { // card is imported by promo, glyph through card (a default export, but imported): both components, used by promo let comps: Vec<(&str, Vec<&str>)> = r.components.iter().map(|c| (c.file.as_str(), c.used_by.iter().map(String::as_str).collect())).collect(); assert_eq!(comps, [("card.tsx", vec!["promo.tsx"]), ("lib/glyph.tsx", vec!["promo.tsx"])]); - let ctl: Vec<(Option<&str>, &str)> = r.controllers.iter().map(|c| (c.id.as_deref(), c.file.as_str())).collect(); - assert_eq!(ctl, [(Some("delivery"), "controllers/delivery.ts"), (Some("look-and-feel"), "settings/look.ts")]); } #[test] fn what_isnt_connected_is_linted_with_its_place_and_fix() { let (_t, p) = project(); - let r = scan(&p, &[]); + let r = scan(&p); let has = |rule: &str, file: &str, line: usize| r.lint.iter().any(|l| l.rule == rule && l.file == file && l.line == line); assert!(has("orphan", "stray.tsx", 1)); assert!(!r.lint.iter().any(|l| l.rule == "orphan" && ["card.tsx", "lib/glyph.tsx", "promo.tsx"].contains(&l.file.as_str()))); @@ -83,8 +79,6 @@ fn what_isnt_connected_is_linted_with_its_place_and_fix() { assert!(has("duplicate-id", "teaser.tsx", 4)); assert!(r.lint.iter().filter(|l| l.rule == "duplicate-id").all(|l| l.says.contains("teaser") || l.file == "teaser.tsx")); assert!(has("computed", "promo.tsx", 5)); - assert!(has("controller-home", "settings/look.ts", 3)); - assert!(!r.lint.iter().any(|l| l.file == "controllers/delivery.ts")); // a default export with a render is registered by --fix; a nameless one says how let bare = r.lint.iter().find(|l| l.rule == "unregistered" && l.file == "bare.tsx").unwrap(); assert!(bare.action.is_some()); @@ -94,44 +88,37 @@ fn what_isnt_connected_is_linted_with_its_place_and_fix() { assert!(!r.lint.iter().any(|l| l.rule == "orphan" && l.file == "shots.tsx")); assert!(has("computed-root", "shots.tsx", 1)); // as Findings (DR3): about the file at its line, a fix --fix applies saying so, the count last - let home = r.lint.iter().find(|l| l.rule == "controller-home").unwrap().finding(); - assert_eq!((home.about[0].key.as_deref(), home.fix.as_deref().map(|f| f.starts_with("raea doctor --fix does it: move it to"))), (Some("settings/look.ts:3"), Some(true))); + let stray = r.lint.iter().find(|l| l.rule == "orphan" && l.file == "stray.tsx").unwrap().finding(); + assert_eq!((stray.about[0].key.as_deref(), stray.fix.as_deref().map(|f| f.starts_with("register it"))), (Some("stray.tsx:1"), Some(true))); + let bare = bare.finding(); + assert_eq!((bare.about[0].key.as_deref(), bare.fix.as_deref().map(|f| f.starts_with("raea doctor --fix registers it"))), (Some("bare.tsx:1"), Some(true)), "a fix --fix applies says so"); assert!(r.text().lines().last().unwrap().starts_with("raea project scan: 0 errors, ")); } #[test] -fn fixes_register_a_default_export_and_move_a_controller_home() { +fn a_fix_registers_a_default_export() { let (_t, p) = project(); - let r = scan(&p, &[]); + let r = scan(&p); for l in r.lint.iter().filter(|l| l.action.is_some()) { lint::apply(l.action.as_ref().unwrap()).unwrap(); } let bare = std::fs::read_to_string(p.join("bare.tsx")).unwrap(); assert!(bare.starts_with("import { Composition, registerRoot } from \"raea\";\nimport { AbsoluteFill }"), "{bare}"); assert!(bare.ends_with("registerRoot(() => );\n"), "{bare}"); - assert!(p.join("controllers/look-and-feel.ts").is_file() && !p.join("settings/look.ts").exists()); - let again = scan(&p, &[]); + let again = scan(&p); assert_eq!(again.compositions.iter().find(|c| c.file == "bare.tsx").unwrap().how, How::Registered); - assert!(!again.lint.iter().any(|l| l.rule == "controller-home" || (l.rule == "unregistered" && l.file == "bare.tsx"))); + assert!(!again.lint.iter().any(|l| l.rule == "unregistered" && l.file == "bare.tsx")); } #[test] fn a_folder_outside_any_project_says_so() { let t = tempdir::Dir::new(); std::fs::write(t.0.join("a.tsx"), "export default function A() { return null; }\n").unwrap(); - let r = scan(&t.0, &[]); + let r = scan(&t.0); assert!(!r.project); assert!(r.lint.iter().any(|l| l.rule == "not-a-project")); } -#[test] -fn an_override_naming_a_controller_that_isnt_there_is_linted() { - let (_t, p) = project(); - let r = scan(&p, &["delivery".into(), "gone".into(), "gone".into()]); - let named: Vec<&str> = r.lint.iter().filter(|l| l.rule == "override-missing").map(|l| l.says.as_str()).collect(); - assert_eq!(named, ["overrides controller \"gone\", which isn't there"], "once, and not for one that's there"); -} - #[test] fn versions_share_a_stem() { assert_eq!(stem("promo-v12.tsx"), "promo"); @@ -145,7 +132,7 @@ fn versions_share_a_stem() { fn real_folder() { let Some(dir) = std::env::var_os("RAEA_SCAN_DIR") else { return }; let t = std::time::Instant::now(); - let r = scan(Path::new(&dir), &[]); + let r = scan(Path::new(&dir)); println!("{}\n({} ms)", r.text(), t.elapsed().as_millis()); } @@ -165,7 +152,7 @@ fn a_project_in_the_layout_reaches_shared_and_says_whats_out_of_place() { w("projects/a/compositions/main.tsx", "import { Desk } from \"@shared/components/desk\";\nimport { Leg } from \"../components/leg\";\nimport { Desk as D2 } from \"../../../shared/components/desk\";\nexport default () => <>;\n"); w("projects/a/components/leg.tsx", "export function Leg() { return ; }\n"); w("projects/a/loose.tsx", "export default () => ;\n"); - let r = scan(&t.0.join("projects/a"), &[]); + let r = scan(&t.0.join("projects/a")); let says = |rule: &str| r.lint.iter().filter(|l| l.rule == rule).map(|l| format!("{} {}: {}", l.file, l.says, l.fix)).collect::>(); assert!(says("unresolved").is_empty(), "{:?}", says("unresolved")); let outside = says("outside"); @@ -177,7 +164,7 @@ fn a_project_in_the_layout_reaches_shared_and_says_whats_out_of_place() { w("projects/old/.raea/project", "[project]\n\tid = pj-old\n"); w("projects/old/promo.tsx", "import { Card } from \"./card\";\nexport default () => ;\n"); w("projects/old/card.tsx", "export function Card() { return ; }\n"); - let r = scan(&t.0.join("projects/old"), &[]); + let r = scan(&t.0.join("projects/old")); let old: Vec<_> = r.lint.iter().filter(|l| l.rule == "old-layout").collect(); assert!(old.len() == 1 && old[0].says.contains("2 files loose") && old[0].fix.contains("raea project tidy"), "{:?}", r.lint); assert!(!r.lint.iter().any(|l| l.rule == "misplaced")); diff --git a/apps/workspace/src/controllers.rs b/apps/workspace/src/controllers.rs deleted file mode 100644 index 6e7f6abf4..000000000 --- a/apps/workspace/src/controllers.rs +++ /dev/null @@ -1,209 +0,0 @@ -//! A workspace's controllers on disk (docs/projects.feature PJ2): shared/controllers/.ts (docs/layout.feature; a -//! workspace from before shared/ keeps controllers/ at its root), each `export default -//! controller({...})` from "raea/brief", checked by core/brief's normalize. A project overrides a field's value in its -//! .raea/project (`[controller "delivery.format"] aspect-ratio = 16:9`), so the project's value wins, as git config's -//! own scopes do. Every change is a commit by who made it ("you", or the agent's name with --by). -use super::*; -use raea_core_brief::controller::{self as ctl, Controller, Field, Kind}; - -use std::process::Command; - -const USAGE: &str = "usage: raea controller ls [--json] | get PATH [--json] | set PATH VALUE [--project] [--by NAME] | write FILE.ts [--by NAME] | rm ID [--by NAME]\n (PATH is controller.group.field; a VALUE is JSON for numbers, toggles and lists, else text)"; - -fn workspace_dir() -> R { - let here = std::env::current_dir().map_err(|e| e.to_string())?; - workspace::up(&here, ".raea/workspace").ok_or_else(|| "not in a workspace: raea workspace init NAME makes one".to_string()) -} - -/// Every controller in the workspace, checked, in file order. -pub fn load(ws: &Path, eval: Eval) -> R> { - let mut files: Vec = std::fs::read_dir(raea_app_registry::shared_dir(ws, "controllers")).into_iter().flatten().flatten().map(|e| e.path()).filter(|p| p.extension().is_some_and(|x| x == "ts")).collect(); - files.sort(); - files.into_iter().map(|f| read(&f, eval).map(|c| (f, c))).collect() -} - -fn read(f: &Path, eval: Eval) -> R { - ctl::of_json(&eval(f)?).map_err(|e| format!("{}: {e}", f.display())) -} - -/// The module a controller is kept as. -pub fn module(c: &Controller) -> String { - format!("import {{ controller }} from \"raea/brief\";\n\nexport default controller({});\n", ts_literal(&serde_json::to_value(c).unwrap_or_default(), 0)) -} - -/// A field's value as JSON (its kind's `value`). -fn value_of(f: &Field) -> serde_json::Value { - serde_json::to_value(&f.kind).ok().and_then(|v| v.get("value").cloned()).unwrap_or_default() -} - -/// The git-config key for a field's override: `controller...`, which git reads as section -/// controller, subsection ".", key . -fn key(path: &str) -> String { - format!("controller.{path}") -} - -/// A value as typed on the command line or kept in git config: JSON when it parses as JSON of the field's kind, else -/// the text itself (a choice, a text field). -fn parse(f: &Field, s: &str) -> R { - let v = match (&f.kind, serde_json::from_str::(s)) { - (Kind::Text { .. } | Kind::Choice { .. }, Ok(serde_json::Value::String(t))) => serde_json::Value::String(t), - (Kind::Text { .. } | Kind::Choice { .. }, _) => serde_json::Value::String(s.to_string()), - (_, Ok(v)) => v, - (_, Err(_)) => serde_json::Value::String(s.to_string()), - }; - ctl::check_value(f, &v) -} - -/// The overrides of the project `from` is in, by path. -pub(crate) fn overrides(from: &Path) -> Vec<(String, String)> { - let Some(p) = workspace::up(from, ".raea/project") else { return vec![] }; - let text = workspace::config(Some(&p.join(".raea/project")), &["--get-regexp", "^controller\\."]).unwrap_or_default(); - text.lines().filter_map(|l| l.split_once(' ')).map(|(k, v)| (k.trim_start_matches("controller.").to_string(), v.to_string())).collect() -} - -fn commit(ws: &Path, paths: &[&Path], what: &str, by: &str) -> R<()> { - let mut add = Command::new(workspace::program()); - add.arg("-C").arg(ws).args(["add", "-A", "--"]).args(paths); - add.status().map_err(workspace::missing)?; - let ok = workspace::git_cmd().arg("-C").arg(ws).args(["-c", &format!("user.name={by}"), "commit", "-q", "-m", &format!("{by}: {what}"), "--"]).args(paths).status().map_err(workspace::missing)?; - if ok.success() { Ok(()) } else { Err(format!("couldn't commit {what}")) } -} - -/// `raea controller …`, its specs evaluated by `eval` -pub fn controller(args: &[String], eval: Eval) -> R { - let json_out = args.iter().any(|a| a == "--json"); - let by = workspace::flag(args, "--by").unwrap_or("you").trim_start_matches('@').to_string(); - let w: Vec<&str> = args.iter().enumerate().filter(|(i, a)| !a.starts_with("--") && !(*i > 0 && args[i - 1] == "--by")).map(|(_, a)| a.as_str()).collect(); - let ws = workspace_dir()?; - match w.as_slice() { - ["ls"] | [] => ls(&ws, json_out, eval), - ["get", path] => get(&ws, path, json_out, eval), - ["set", path, value] => set(&ws, path, value, args.iter().any(|a| a == "--project"), &by, eval), - ["write", file] => write(&ws, Path::new(file), &by, eval), - ["rm", id] => rm(&ws, id, &by), - _ => Err(USAGE.into()), - } -} - -/// The controllers as `raea controller ls` prints them, with the overrides of the project `from` is in: what `raea -/// context` shows an agent. None outside a workspace or when it has no controllers. -pub fn summary(from: &Path, eval: Eval) -> Option { - let ws = workspace::up(from, ".raea/workspace")?; - load(&ws, eval).ok().filter(|cs| !cs.is_empty())?; - ls_from(&ws, from, false, eval).ok() -} - -fn ls(ws: &Path, json_out: bool, eval: Eval) -> R { - ls_from(ws, &std::env::current_dir().map_err(|e| e.to_string())?, json_out, eval) -} - -fn ls_from(ws: &Path, from: &Path, json_out: bool, eval: Eval) -> R { - let cs = load(ws, eval)?; - let over = overrides(from); - let mut rows = vec![]; - for (_, c) in &cs { - for g in &c.groups { - for f in &g.fields { - let path = format!("{}.{}.{}", c.id, g.id, f.id); - let mine = over.iter().find(|(k, _)| *k == path).and_then(|(_, v)| parse(f, v).ok()); - rows.push((path, f, mine.clone().unwrap_or_else(|| value_of(f)), mine.is_some())); - } - } - } - if json_out { - let fields: Vec<_> = rows.iter().map(|(p, f, v, o)| json!({"path": p, "label": f.label, "type": serde_json::to_value(&f.kind).ok().and_then(|k| k.get("type").cloned()), "value": v, "project": o})).collect(); - let list: Vec<_> = cs.iter().map(|(_, c)| serde_json::to_value(c).map(|v| tidy_deep(&v)).unwrap_or_default()).collect(); - return Ok(json!({"controllers": list, "fields": fields}).to_string()); - } - if cs.is_empty() { - return Ok("no controllers yet: raea controller write FILE.ts adds one (`export default controller({ title, groups })` from \"raea/brief\")".into()); - } - let mut out = String::new(); - for (_, c) in &cs { - out.push_str(&format!("{} ({})\n", c.title, c.id)); - for (p, f, v, o) in rows.iter().filter(|r| r.0.starts_with(&format!("{}.", c.id))) { - out.push_str(&format!(" {p} {}: {}{}\n", f.label, tidy(v), if *o { " (this project)" } else { "" })); - } - } - Ok(out.trim_end().to_string()) -} - -/// Where a path's field is: its controller, group and field, by index. -fn locate(cs: &[(PathBuf, Controller)], path: &str) -> R<(usize, usize, usize)> { - let mut p = path.splitn(3, '.'); - let (c, g, f) = (p.next().unwrap_or(""), p.next().unwrap_or(""), p.next().unwrap_or("")); - let ci = cs.iter().position(|x| x.1.id == c); - let gi = ci.and_then(|ci| cs[ci].1.groups.iter().position(|y| y.id == g)); - let fi = ci.zip(gi).and_then(|(ci, gi)| cs[ci].1.groups[gi].fields.iter().position(|z| z.id == f)); - match (ci, gi, fi) { - (Some(c), Some(g), Some(f)) => Ok((c, g, f)), - _ => Err(format!("no field at {path}: raea controller ls lists the paths (controller.group.field)")), - } -} - -fn find<'a>(cs: &'a [(PathBuf, Controller)], path: &str) -> R<&'a Field> { - let (c, g, f) = locate(cs, path)?; - Ok(&cs[c].1.groups[g].fields[f]) -} - -fn get(ws: &Path, path: &str, json_out: bool, eval: Eval) -> R { - let cs = load(ws, eval)?; - let f = find(&cs, path)?; - let here = std::env::current_dir().map_err(|e| e.to_string())?; - let mine = overrides(&here).into_iter().find(|(k, _)| k == path).map(|(_, v)| parse(f, &v)).transpose()?; - let v = mine.clone().unwrap_or_else(|| value_of(f)); - let v = tidy(&v); - Ok(if json_out { json!({"path": path, "value": v, "project": mine.is_some()}).to_string() } else { v.to_string() }) -} - -fn set(ws: &Path, path: &str, value: &str, project: bool, by: &str, eval: Eval) -> R { - let mut cs = load(ws, eval)?; - let v = parse(find(&cs, path)?, value)?; - if project { - let here = std::env::current_dir().map_err(|e| e.to_string())?; - let p = workspace::up(&here, ".raea/project").ok_or("--project: not in a project")?; - let text = match &v { - serde_json::Value::String(s) => s.clone(), - v => v.to_string(), - }; - let file = p.join(".raea/project"); - workspace::set(&file, &key(path), &text)?; - // a submodule project is its own repo; an inline one commits in the workspace - let repo = if p.join(".git").exists() { p.clone() } else { ws.to_path_buf() }; - commit(&repo, &[&file], &format!("{path} = {text} for this project"), by)?; - return Ok(format!("{path} = {text} (this project)")); - } - let (c, g, f) = locate(&cs, path)?; - let (file, ctrl) = &mut cs[c]; - let field = &mut ctrl.groups[g].fields[f]; - let mut kind = serde_json::to_value(&field.kind).map_err(|e| e.to_string())?; - kind["value"] = v.clone(); - field.kind = serde_json::from_value(kind).map_err(|e| e.to_string())?; - std::fs::write(&*file, module(ctrl)).map_err(|e| format!("{}: {e}", file.display()))?; - let file = file.clone(); - let v = tidy(&v); - let said = v.as_str().map(String::from).unwrap_or_else(|| v.to_string()); - commit(ws, &[&file], &format!("{path} = {said}"), by)?; - Ok(format!("{path} = {v}")) -} - -fn write(ws: &Path, file: &Path, by: &str, eval: Eval) -> R { - let c = read(file, eval)?; - let to = raea_app_registry::shared_dir(ws, "controllers").join(format!("{}.ts", c.id)); - let new = !to.exists(); - std::fs::create_dir_all(raea_app_registry::shared_dir(ws, "controllers")).map_err(|e| e.to_string())?; - std::fs::write(&to, module(&c)).map_err(|e| format!("{}: {e}", to.display()))?; - commit(ws, &[&to], &format!("{} controller {}", if new { "add" } else { "rewrite" }, c.id), by)?; - let n = |k: usize, what: &str| format!("{k} {what}{}", if k == 1 { "" } else { "s" }); - Ok(format!("{}: {} ({}, {})", to.display(), c.title, n(c.groups.len(), "group"), n(c.groups.iter().map(|g| g.fields.len()).sum(), "field"))) -} - -fn rm(ws: &Path, id: &str, by: &str) -> R { - let file = raea_app_registry::shared_dir(ws, "controllers").join(format!("{id}.ts")); - if !file.is_file() { - return Err(format!("no controller {id}: raea controller ls lists them")); - } - std::fs::remove_file(&file).map_err(|e| format!("{}: {e}", file.display()))?; - commit(ws, &[&file], &format!("remove controller {id}"), by)?; - Ok(format!("removed {id} (git revert brings it back)")) -} diff --git a/apps/workspace/src/doctor.rs b/apps/workspace/src/doctor.rs index 7f51a7e41..952af1ccc 100644 --- a/apps/workspace/src/doctor.rs +++ b/apps/workspace/src/doctor.rs @@ -3,7 +3,8 @@ //! repo's git config), and an agent's copy of the raea skill from another version. `raea context` runs the same checks //! and prints CONTEXT_STALE when any finds something, so they stay cheap: file reads and git config, no engine. //! It also lists what in the project isn't connected to raea's project system (docs/projects.feature PJ8, registry.rs): -//! `--fix` registers a default export and moves a stray controller to controllers/, as a commit. +//! `--fix` registers a default export, as a commit. A controller left from before 11-20 is listed with where its parts +//! go, and kept: raea reads none since, and only the person knows which still hold. use super::*; use crate::workspace::{get, git, include, new_id, set}; @@ -69,6 +70,22 @@ fn format(repo: &Path, file: &Path, keys: &[(&str, String)], out: &mut Vec, out: &mut Vec) { + let mut dirs = vec![base.join("controllers")]; + dirs.extend(ws.into_iter().flat_map(|w| [w.join("controllers"), w.join("shared/controllers")])); + dirs.dedup(); + for d in dirs { + let mut files: Vec = std::fs::read_dir(&d).into_iter().flatten().flatten().map(|e| e.path()).filter(|p| p.extension().is_some_and(|x| x == "ts")).collect(); + files.sort(); + for f in files { + let says = format!("{}: a controller, which raea no longer reads; move what still holds (a standing rule or preference to a line in taste.ts, with a check when raea can measure it; a decision for now to a feed post with an ask; a piece's settings into its composition), then delete it", f.display()); + out.push(Finding { says, fix: Fix::No }); + } + } +} + /// The `version:` in a SKILL.md's front matter. fn skill_version(md: &Path) -> Option { let text = std::fs::read_to_string(md).ok()?; @@ -83,6 +100,7 @@ pub fn findings(from: &Path, skills: &[(&str, PathBuf)], version: &str) -> Vec include(repo, file).map(|_| true), (Fix::Skills(agent), true) => reinstall(agent).map(|_| true), (Fix::Registry(r), true) => { - touched.extend(match r { - crate::registry::Fix::Register { file, .. } => vec![file.clone()], - crate::registry::Fix::Move { from, to } => vec![from.clone(), to.clone()], - }); + let crate::registry::Fix::Register { file, .. } = r; + touched.push(file.clone()); crate::registry::apply(r).map(|_| true) } _ => Ok(false), diff --git a/apps/workspace/src/lib.rs b/apps/workspace/src/lib.rs index bc1576458..128422479 100644 --- a/apps/workspace/src/lib.rs +++ b/apps/workspace/src/lib.rs @@ -1,28 +1,20 @@ -//! A workspace's folders and files (docs/projects.feature PJ1-PJ4): `raea workspace`, `raea project` (with split and -//! join) and `raea controller`. A workspace is a git repo raea changes by commits; its controllers are spec modules, -//! which the raea CLI evaluates on the engine and hands in as an `Eval`, so this crate needs no engine of its own. +//! A workspace's folders and files (docs/projects.feature PJ1-PJ4): `raea workspace` and `raea project` (with split +//! and join). A workspace is a git repo raea changes by commits. use std::path::{Path, PathBuf}; use serde_json::json; -mod controllers; pub mod doctor; -mod literal; mod repair; pub mod next; pub mod registry; mod storage; mod workspace; -pub use controllers::{controller, module, summary}; pub use registry::context; -pub use literal::{tidy, tidy_deep, ts_literal}; pub use workspace::{default_root, project, projects, root, slug, up, workspace}; pub type R = Result; -/// A spec module's default export as JSON: the raea CLI's spec_json, which runs it on the engine. -pub type Eval = fn(&Path) -> R; - #[cfg(test)] mod tests; diff --git a/apps/workspace/src/literal.rs b/apps/workspace/src/literal.rs deleted file mode 100644 index ee908400d..000000000 --- a/apps/workspace/src/literal.rs +++ /dev/null @@ -1,37 +0,0 @@ -//! Spec modules as raea writes them: a value as a TypeScript literal, and whole numbers kept whole. -/// A value as a TypeScript literal for a spec module: unquoted keys where they can be, nulls and empty lists left out. -pub fn ts_literal(v: &serde_json::Value, indent: usize) -> String { - use serde_json::Value; - let (pad, end) = (" ".repeat(indent + 1), " ".repeat(indent)); - match v { - Value::Array(a) if a.iter().all(Value::is_string) && v.to_string().len() < 70 => format!("[{}]", a.iter().map(Value::to_string).collect::>().join(", ")), - Value::Array(a) => format!("[\n{}{end}]", a.iter().map(|x| format!("{pad}{},\n", ts_literal(x, indent + 1))).collect::()), - Value::Object(o) => { - let ident = |k: &str| k.chars().next().is_some_and(|c| c.is_ascii_alphabetic() || c == '_') && k.chars().all(|c| c.is_ascii_alphanumeric() || c == '_'); - let kept = o.iter().filter(|(_, x)| !x.is_null() && !x.as_array().is_some_and(Vec::is_empty)); - let body: String = kept.map(|(k, x)| format!("{pad}{}: {},\n", if ident(k) { k.clone() } else { Value::String(k.clone()).to_string() }, ts_literal(x, indent + 1))).collect(); - format!("{{\n{body}{end}}}") - } - v => tidy(v).to_string(), - } -} - -/// A number that's whole (as f64 values from Rust are, 45.0) written as an integer. -pub fn tidy(v: &serde_json::Value) -> serde_json::Value { - match v.as_f64() { - Some(n) if v.is_f64() && n.fract() == 0.0 && n.abs() < 1e15 => serde_json::Value::from(n as i64), - _ => match v { - serde_json::Value::Array(a) => serde_json::Value::Array(a.iter().map(tidy).collect()), - v => v.clone(), - }, - } -} - -/// `tidy` through a whole value: objects and arrays too. -pub fn tidy_deep(v: &serde_json::Value) -> serde_json::Value { - match v { - serde_json::Value::Object(o) => serde_json::Value::Object(o.iter().filter(|(_, x)| !x.is_null()).map(|(k, x)| (k.clone(), tidy_deep(x))).collect()), - serde_json::Value::Array(a) => serde_json::Value::Array(a.iter().map(tidy_deep).collect()), - v => tidy(v), - } -} diff --git a/apps/workspace/src/registry.rs b/apps/workspace/src/registry.rs index 715ed78d0..263870dfb 100644 --- a/apps/workspace/src/registry.rs +++ b/apps/workspace/src/registry.rs @@ -1,25 +1,9 @@ -//! A project's compositions, components and controllers (docs/projects.feature PJ8): raea-app-registry's reading of -//! its files, with the project's controller overrides from .raea/project checked against the controllers there. +//! A project's compositions and components (docs/projects.feature PJ8): raea-app-registry's reading of its files. use std::path::Path; -use crate::Eval; -pub use raea_app_registry::{Component, Composition, Controller, Fix, How, Level, Lint, Prop, Registry, apply}; +pub use raea_app_registry::{Component, Composition, Fix, How, Level, Lint, Prop, Registry, apply, scan}; -/// The folder's registry. -pub fn scan(dir: &Path) -> Registry { - let ids: Vec = crate::controllers::overrides(dir).into_iter().filter_map(|(path, _)| path.split('.').next().map(str::to_string)).collect(); - raea_app_registry::scan(dir, &ids) -} - -/// What `raea context` reads of the workspace, as (section, text): its controllers with this project's overrides, and -/// the project's compositions, components and controllers as raea reads them. -pub fn context(from: &Path, eval: Eval) -> Vec<(String, String)> { - let mut out = Vec::new(); - if let Some(text) = crate::summary(from, eval) { - out.push(("CONTROLLERS (raea controller ls; a project's own values marked)".to_string(), text)); - } - if let Some(dir) = crate::doctor::registry_dir(from) { - out.push(("PROJECT FILES (raea project scan)".to_string(), scan(&dir).summary())); - } - out +/// What `raea context` reads of the project, as (section, text): its compositions and components as raea reads them. +pub fn context(from: &Path) -> Vec<(String, String)> { + crate::doctor::registry_dir(from).map(|dir| ("PROJECT FILES (raea project scan)".to_string(), scan(&dir).summary())).into_iter().collect() } diff --git a/apps/workspace/src/tests.rs b/apps/workspace/src/tests.rs index 22c5cb549..bb70cf7c9 100644 --- a/apps/workspace/src/tests.rs +++ b/apps/workspace/src/tests.rs @@ -6,20 +6,6 @@ fn a_name_is_its_folder() { assert_eq!(slug(" CJ / Reel 2 "), "cj-reel-2"); } -#[test] -fn a_spec_module_is_tidy_typescript() { - // keys unquoted where they can be, nulls and empty lists left out, whole numbers whole, short string lists inline - let v = json!({"id": "delivery", "help": null, "tags": [], "n": 45.0, "options": ["9:16", "16:9"], "odd-key": 1}); - // the keys' order is serde_json's: sorted on its own, as written when a crate built alongside turns on - // preserve_order (raea-cli does), so the lines are held as a set (#90) - fn lines(s: &str) -> Vec<&str> { - let mut l: Vec<&str> = s.lines().collect(); - l.sort_unstable(); - l - } - assert_eq!(lines(&ts_literal(&v, 0)), lines("{\n id: \"delivery\",\n n: 45,\n \"odd-key\": 1,\n options: [\"9:16\", \"16:9\"],\n}")); -} - #[test] fn up_finds_the_nearest_marker() { let root = dunce::canonicalize(std::env::temp_dir()).unwrap().join(format!("raea-ws-up-{}", std::process::id())); @@ -95,15 +81,16 @@ fn doctor_connects_a_projects_files() { std::fs::create_dir_all(d.join(".raea")).unwrap(); std::fs::write(d.join(".raea/project"), "").unwrap(); std::fs::write(d.join("loose.tsx"), "export const Loose = () => null;\n").unwrap(); - std::fs::write(d.join("pace.ts"), "import { controller } from \"raea/brief\";\nexport default controller({ title: \"Pace\", fields: {} });\n").unwrap(); + std::fs::create_dir_all(d.join("controllers")).unwrap(); + std::fs::write(d.join("controllers/pace.ts"), "import { controller } from \"raea/brief\";\nexport default controller({ title: \"Pace\", fields: {} });\n").unwrap(); let found = doctor::registry_findings(&d); let says: Vec<&String> = found.iter().map(|f| &f.says).collect(); - assert_eq!(found.len(), 2, "{says:?}"); + assert_eq!(found.len(), 1, "{says:?}"); assert!(says[0].contains("loose.tsx:1: isn't a composition") && !found[0].fixable(), "{says:?}"); - assert!(says[1].contains("pace.ts:2: a controller outside controllers/") && found[1].fixable(), "{says:?}"); + // a controller from before 11-20 is told where its parts go, and kept let out = doctor::doctor(&["--fix".into(), d.display().to_string()], &[], "0.0.1", &|_| Ok(String::new())).unwrap(); - assert!(out.starts_with("APPLIED 3 of 4 fixed") && out.contains("fixed ") && d.join("controllers/pace.ts").is_file() && !d.join("pace.ts").exists(), "{out}"); - assert_eq!(doctor::registry_findings(&d).len(), 1, "only the loose file is left"); + assert!(out.starts_with("APPLIED 2 of 4 fixed") && out.contains("controllers/pace.ts: a controller, which raea no longer reads") && out.contains("taste.ts"), "{out}"); + assert!(d.join("controllers/pace.ts").is_file(), "nothing of the person's is deleted"); let _ = std::fs::remove_dir_all(&d); } diff --git a/apps/workspace/src/workspace.rs b/apps/workspace/src/workspace.rs index 8d36c5cb9..3449a7325 100644 --- a/apps/workspace/src/workspace.rs +++ b/apps/workspace/src/workspace.rs @@ -98,8 +98,8 @@ fn words(args: &[String]) -> Vec<&str> { raea_app_check::words(args, &["--layout", "--storage", "--name", "--remote"]) } -// a name as a folder (slug), and the nearest folder holding a marker (up): the registry's, which reads controller ids -// and projects with them +// a name as a folder (slug), and the nearest folder holding a marker (up): the registry's, which reads projects with +// them pub use raea_app_registry::{slug, up}; /// A new id: the prefix and eight hex digits from the clock and the process. @@ -188,10 +188,10 @@ pub(crate) fn commit(repo: &Path, paths: &[&str], what: &str) -> R<()> { git(repo, &["commit", "-q", "-m", &format!("raea: {what}"), "--"]).map(|_| ()) } -const AGENTS_PROJECT: &str = "# Agents\n\nRun `raea context .` here before any work: the taste, this project's brief.ts and script.ts, its look and the guides\nits modes need, in the order to read them. Specs are TypeScript (`export default brief({...})` from \"raea/brief\").\n\nWhere files go (docs/layout.feature):\n\n- compositions/: what renders, a registerRoot or a default export; versions are NAME-v2.tsx\n- components/: what compositions import; every prop is a component whose props animate it\n- controllers/: this project's controllers, over the workspace's shared ones by id\n- assets/: media in (footage, stills, audio, models, fonts) and the brand kit in assets/brand/\n- artifacts/: the small React apps posted to the feed\n- out/: renders\n\nThe workspace's shared/ holds the same five folders for every project: import them as\n`@shared/components/desk`, never by a relative path out of this folder.\n"; +const AGENTS_PROJECT: &str = "# Agents\n\nRun `raea context .` here before any work: the taste, this project's brief.ts and script.ts, its look and the guides\nits modes need, in the order to read them. Specs are TypeScript (`export default brief({...})` from \"raea/brief\").\n\nWhere files go (docs/layout.feature):\n\n- compositions/: what renders, a registerRoot or a default export; versions are NAME-v2.tsx\n- components/: what compositions import; every prop is a component whose props animate it\n- assets/: media in (footage, stills, audio, models, fonts) and the brand kit in assets/brand/\n- artifacts/: the small React apps posted to the feed\n- out/: renders\n\nThe workspace's shared/ holds the same five folders for every project: import them as\n`@shared/components/desk`, never by a relative path out of this folder.\n"; /// The kinds of file a project, and the workspace's shared/, keep a folder each for (docs/layout.feature). -pub const KINDS: [&str; 5] = ["compositions", "components", "controllers", "assets", "artifacts"]; +pub const KINDS: [&str; 4] = ["compositions", "components", "assets", "artifacts"]; /// LFS for media in and renders out, at any depth: in each project and in shared/ (a pattern with a slash is anchored to /// the workspace root, so the old media/** never matched a project's media/) @@ -362,7 +362,7 @@ pub fn project(args: &[String]) -> R { Some("new") => new_project(w.get(1).ok_or(USAGE)?, flag(args, "--storage")), Some("split") => storage::split(w.get(1).ok_or(USAGE)?, flag(args, "--remote")), Some("join") => storage::join(w.get(1).ok_or(USAGE)?), - // PJ8: the folder's compositions, components and controllers, and what isn't connected + // PJ8: the folder's compositions and components, and what isn't connected Some("scan") => { let dir = w.get(1).map(PathBuf::from).map_or_else(|| std::env::current_dir().map_err(|e| e.to_string()), Ok)?; let r = crate::registry::scan(&dir); @@ -428,17 +428,12 @@ fn show_project(json_out: bool) -> R { let dir = up(&here, ".raea/project").ok_or("not in a project: raea project new NAME (in a workspace) makes one")?; let file = dir.join(".raea/project"); let ws = up(&dir, ".raea/workspace").filter(|w| *w != dir); - let overrides: Vec<(String, String)> = all(&file).into_iter().filter(|(k, _)| k.starts_with("controller.")).collect(); if json_out { - let o: serde_json::Map = overrides.iter().map(|(k, v)| (k.trim_start_matches("controller.").to_string(), json!(v))).collect(); - return Ok(json!({"path": dir, "id": get(&file, "project.id"), "name": get(&file, "project.name"), "workspace": ws, "controllers": o}).to_string()); + return Ok(json!({"path": dir, "id": get(&file, "project.id"), "name": get(&file, "project.name"), "workspace": ws}).to_string()); } let mut out = format!("{} ({})\n{}\n", get(&file, "project.name").unwrap_or_default(), get(&file, "project.id").unwrap_or_default(), dir.display()); if let Some(ws) = &ws { out.push_str(&format!("in workspace {}\n", ws.display())); } - for (k, v) in overrides { - out.push_str(&format!(" {} = {v}\n", k.trim_start_matches("controller."))); - } Ok(out.trim_end().to_string()) } diff --git a/bench/direction/proof/controllers/rules.ts b/bench/direction/proof/controllers/rules.ts deleted file mode 100644 index 39245a63c..000000000 --- a/bench/direction/proof/controllers/rules.ts +++ /dev/null @@ -1,19 +0,0 @@ -// The proof project's rules (docs/direction.feature DR4): each a rule field naming the check that holds it, a .ts -// check by its path from here, with its values. `raea check FILE.tsx --only ID` runs one. -import { controller } from "raea/brief"; - -export default controller({ - title: "Proof rules", - groups: [ - { - title: "What the pieces are held to", - fields: [ - { label: "Sung lines are flat 2D type, inside the frame, behind the subject", type: "rule", check: "../checks/lyric.ts" }, - { label: "Cuts land on a word's end", type: "rule", check: "../checks/cut.ts" }, - { label: "Cues are heard where they are placed", type: "rule", check: "../checks/cue.ts" }, - { label: "Captions clear the button band", type: "rule", check: "../checks/caption.ts", values: { band: 0.8 } }, - { label: "The rider turns with its seat and is in no part of it", type: "rule", check: "../checks/rider.ts", values: { rider: "rider", seat: "seat" } }, - ], - }, - ], -}); diff --git a/bench/direction/proof/proof.sh b/bench/direction/proof/proof.sh index 335728c7a..7a50a4d6d 100644 --- a/bench/direction/proof/proof.sh +++ b/bench/direction/proof/proof.sh @@ -1,8 +1,9 @@ #!/usr/bin/env bash # DR4's proof (docs/direction.feature): five checks written as systems over the world (checks/*.ts, none importing -# Bevy), each run by `raea check` on a piece that holds it and on a cheat that must fail it, and a taste line run as -# the named check of its form beside them. Its media are made here with ffmpeg (nothing downloaded); the two pieces -# whose checks need a render are rendered first. Every case runs in a copy, so the bench folder stays clean. +# Bevy), each a line in the project's taste.ts run by `raea check` on a piece that holds it and on a cheat that must +# fail it, and a taste line run as the named check of its form beside them. Its media are made here with ffmpeg +# (nothing downloaded); the two pieces whose checks need a render are rendered first. Every case runs in a copy, so the +# bench folder stays clean. # # RAEA_BIN=path/to/raea bash bench/direction/proof/proof.sh set -uo pipefail diff --git a/bench/direction/proof/ride.tsx b/bench/direction/proof/ride.tsx index 56f679f6a..50179a271 100644 --- a/bench/direction/proof/ride.tsx +++ b/bench/direction/proof/ride.tsx @@ -1,5 +1,5 @@ // DR4's proof, the 3D scene as asked: a seat turning, and a rider on it that turns with it and sits forward, clear of -// the back (seat.tsx). checks/rider.ts holds it, with the parts named in controllers/rules.ts. +// the back (seat.tsx). checks/rider.ts holds it, with the parts named in taste.ts. import { Composition, registerRoot, useCurrentFrame } from "raea"; import { Seat } from "./seat"; diff --git a/bench/direction/proof/taste.ts b/bench/direction/proof/taste.ts index 6ca422abd..f1672de06 100644 --- a/bench/direction/proof/taste.ts +++ b/bench/direction/proof/taste.ts @@ -1,8 +1,21 @@ -// The proof's taste (passed with --taste): one line raea measures, run as the named check of its form (text-above) -// beside the project's own checks. +// The proof project's taste (docs/direction.feature DR4): its rules, each a line with the check that holds it. A .ts +// check by its path from here, with its values, or one of raea's forms (text-above), which the two taste cases pass +// with --taste. `raea check FILE.tsx --only ID` runs one. import { taste } from "raea/brief"; export default taste({ title: "Proof taste", - sections: [{ heading: "Text", rules: [{ text: "Captions sit above three quarters of the frame.", check: { form: "text-above", value: 75 } }] }], + sections: [ + { + heading: "What the pieces are held to", + rules: [ + { text: "Sung lines are flat 2D type, inside the frame, behind the subject", check: "checks/lyric.ts" }, + { text: "Cuts land on a word's end", check: "checks/cut.ts" }, + { text: "Cues are heard where they are placed", check: "checks/cue.ts" }, + { text: "Captions clear the button band", check: "checks/caption.ts", values: { band: 0.8 } }, + { text: "The rider turns with its seat and is in no part of it", check: "checks/rider.ts", values: { rider: "rider", seat: "seat" } }, + ], + }, + { heading: "Text", rules: [{ text: "Captions sit above three quarters of the frame.", check: { form: "text-above", value: 75 } }] }, + ], }); diff --git a/core/brief/src/controller.rs b/core/brief/src/controller.rs deleted file mode 100644 index 2be4d60ef..000000000 --- a/core/brief/src/controller.rs +++ /dev/null @@ -1,224 +0,0 @@ -//! A workspace's controllers: settings its Director puts together with the person, out of a small set of parts. A -//! controller has groups, a group has typed fields, and every agent in the workspace works to the values (`describe`). -//! The agent writes one as `controllers/.ts` (`export default controller({...})`, docs/projects.feature PJ2); -//! `normalize` checks it and fills in ids, with errors in a sentence the agent can act on. The same contract as -//! apps/app src/controllers/types.ts, whose page reads these types. - -use serde::{Deserialize, Serialize}; -use serde_json::{Map, Value}; -use ts_rs::TS; - -#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, TS)] -#[ts(optional_fields)] -pub struct Controller { - pub id: String, - pub title: String, - #[serde(skip_serializing_if = "Option::is_none")] pub help: Option, - pub groups: Vec, -} - -#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, TS)] -#[ts(optional_fields)] -pub struct Group { - pub id: String, - pub title: String, - #[serde(skip_serializing_if = "Option::is_none")] pub help: Option, - pub fields: Vec, -} - -#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, TS)] -#[ts(optional_fields)] -pub struct Field { - pub id: String, - pub label: String, - #[serde(skip_serializing_if = "Option::is_none")] pub help: Option, - #[serde(flatten)] - #[ts(flatten)] - pub kind: Kind, -} - -/// One step of a workflow field: who does it (an agent's name, or "you" for the person) and where a failure goes back to. -#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, TS)] -#[ts(optional_fields)] -pub struct Step { - pub name: String, - #[serde(skip_serializing_if = "Option::is_none")] pub by: Option, - #[serde(skip_serializing_if = "Option::is_none")] pub back: Option, -} - -#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, TS)] -#[serde(tag = "type", rename_all = "lowercase")] -#[ts(optional_fields)] -pub enum Kind { - Toggle { value: bool }, - Choice { options: Vec, value: String }, - Number { value: f64, #[serde(skip_serializing_if = "Option::is_none")] unit: Option, #[serde(skip_serializing_if = "Option::is_none")] min: Option, #[serde(skip_serializing_if = "Option::is_none")] max: Option, #[serde(skip_serializing_if = "Option::is_none")] step: Option }, - Text { value: String, #[serde(skip_serializing_if = "Option::is_none")] placeholder: Option, #[serde(skip_serializing_if = "Option::is_none")] multiline: Option }, - List { value: Vec, #[serde(skip_serializing_if = "Option::is_none")] placeholder: Option }, - Agents { value: Vec }, - Channels { value: Vec }, - /// steps in order; `channels` run it (all of them when unset) - Workflow { value: Vec, #[serde(skip_serializing_if = "Option::is_none")] channels: Option> }, - /// MCP servers: URLs, commands or GitHub repos, given to every agent's session - Servers { value: Vec }, - /// skills: links to SKILL.md, read into every agent's context - Skills { value: Vec }, - /// a rule the work is held to, its label the rule's words (docs/direction.feature DR4): `check` is one of raea's - /// checks by name with its `values`, or a path to the project's own check (a .ts file, from the controller's - /// folder); `level` is error (when unset), warn or note. `raea check` runs it. - Rule { - check: String, - #[serde(skip_serializing_if = "Option::is_none")] - #[ts(type = "Record")] - values: Option>, - #[serde(skip_serializing_if = "Option::is_none")] level: Option, - }, -} - -const TYPES: &str = "toggle, choice, number, text, list, agents, channels, workflow, servers, skills, rule"; - -fn slug(s: &str) -> String { - let mut out = String::new(); - for c in s.to_lowercase().chars() { - if c.is_ascii_alphanumeric() { - out.push(c); - } else if !out.ends_with('-') { - out.push('-'); - } - } - let out: String = out.trim_matches('-').chars().take(48).collect(); - if out.is_empty() { "x".into() } else { out.trim_end_matches('-').into() } -} - -fn is_id(s: &str) -> bool { - let b = s.as_bytes(); - !b.is_empty() && b.len() <= 48 && b[0].is_ascii_lowercase() && b.iter().all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || *c == b'-') -} - -fn text(o: &Map, k: &str) -> Option { - o.get(k).and_then(Value::as_str).map(str::trim).filter(|s| !s.is_empty()).map(String::from) -} - -fn id_of(o: &Map, fallback: &str) -> String { - o.get("id").and_then(Value::as_str).filter(|s| is_id(s)).map(String::from).unwrap_or_else(|| slug(fallback)) -} - -fn strings(v: Option<&Value>, what: &str) -> Result, String> { - match v { - None | Some(Value::Null) => Ok(vec![]), - Some(Value::Array(a)) if a.iter().all(Value::is_string) => { - Ok(a.iter().filter_map(Value::as_str).map(str::trim).filter(|s| !s.is_empty()).map(String::from).collect()) - } - _ => Err(format!("{what} must be a list of strings")), - } -} - -fn number(o: &Map, k: &str) -> Option { - o.get(k).and_then(Value::as_f64).filter(|n| n.is_finite()) -} - -fn steps(v: Option<&Value>, at: &str) -> Result, String> { - let Some(Value::Array(a)) = v else { return Err(format!("{at}: a workflow's value is a list of steps: {{ name, by?, back? }}")) }; - a.iter() - .enumerate() - .map(|(i, s)| { - let o = s.as_object().ok_or_else(|| format!("{at}: step {} needs a name", i + 1))?; - let name = text(o, "name").ok_or_else(|| format!("{at}: step {} needs a name", i + 1))?; - Ok(Step { name, by: text(o, "by").map(|b| b.trim_start_matches('@').to_string()), back: text(o, "back") }) - }) - .collect() -} - -/// A field as the agent wrote it, checked and filled in; an error names the field and what it needs. -pub fn normalize_field(raw: &Value, at: &str) -> Result { - let o = raw.as_object().ok_or_else(|| format!("{at}: a field is an object"))?; - let label = text(o, "label").ok_or_else(|| format!("{at}: a field needs a label"))?; - let id = id_of(o, &label); - let w = format!("{at}.{id}"); - let value = o.get("value"); - let kind = match o.get("type").and_then(Value::as_str) { - Some("toggle") => Kind::Toggle { value: value == Some(&Value::Bool(true)) }, - Some("choice") => { - let options = strings(o.get("options"), &format!("{w}: options"))?; - if options.len() < 2 { - return Err(format!("{w}: a choice needs at least two options")); - } - let value = value.and_then(Value::as_str).filter(|v| options.iter().any(|x| x == v)).map(String::from).unwrap_or_else(|| options[0].clone()); - Kind::Choice { options, value } - } - Some("number") => Kind::Number { value: number(o, "value").unwrap_or(0.0), unit: o.get("unit").and_then(Value::as_str).map(String::from), min: number(o, "min"), max: number(o, "max"), step: number(o, "step") }, - Some("text") => Kind::Text { value: value.and_then(Value::as_str).unwrap_or("").into(), placeholder: o.get("placeholder").and_then(Value::as_str).map(String::from), multiline: Some(o.get("multiline") == Some(&Value::Bool(true))) }, - Some("list") => Kind::List { value: strings(value, &format!("{w}: value"))?, placeholder: o.get("placeholder").and_then(Value::as_str).map(String::from) }, - Some("agents") => Kind::Agents { value: strings(value, &format!("{w}: value"))? }, - Some("channels") => Kind::Channels { value: strings(value, &format!("{w}: value"))? }, - Some("servers") => Kind::Servers { value: strings(value, &format!("{w}: value"))? }, - Some("skills") => Kind::Skills { value: strings(value, &format!("{w}: value"))? }, - Some("workflow") => Kind::Workflow { value: steps(value, &w)?, channels: o.get("channels").map(|c| strings(Some(c), &format!("{w}: channels"))).transpose()? }, - Some("rule") => { - let check = text(o, "check").ok_or_else(|| format!("{w}: a rule needs a check: one of raea's by name, or a path to a .ts check"))?; - let level = text(o, "level"); - if level.as_deref().is_some_and(|l| !matches!(l, "error" | "warn" | "note")) { - return Err(format!("{w}: a rule's level is error, warn or note")); - } - Kind::Rule { check, values: o.get("values").and_then(Value::as_object).cloned(), level } - } - _ => return Err(format!("{w}: type must be one of {TYPES}")), - }; - Ok(Field { id, label, help: text(o, "help"), kind }) -} - -/// A controller as the agent wrote it (a module's default export, as JSON), checked: ids filled in from titles, each -/// field's value of its type. -pub fn normalize(raw: &Value) -> Result { - let o = raw.as_object().filter(|o| text(o, "title").is_some()).ok_or("a controller needs a title")?; - let title = text(o, "title").unwrap_or_default(); - let id = id_of(o, &title); - let gs = o.get("groups").and_then(Value::as_array).filter(|g| !g.is_empty()).ok_or_else(|| format!("{id}: a controller needs groups: [{{ title, fields: [...] }}]"))?; - let mut groups = vec![]; - for (i, g) in gs.iter().enumerate() { - let g = g.as_object().filter(|g| text(g, "title").is_some()).ok_or_else(|| format!("{id}: group {} needs a title", i + 1))?; - let gtitle = text(g, "title").unwrap_or_default(); - let gid = id_of(g, >itle); - let at = format!("{id}.{gid}"); - let fs = g.get("fields").and_then(Value::as_array).ok_or_else(|| format!("{at}: a group needs fields"))?; - let fields = fs.iter().map(|f| normalize_field(f, &at)).collect::, _>>()?; - if let Some(d) = fields.iter().enumerate().find(|(j, f)| fields.iter().position(|x| x.id == f.id) != Some(*j)) { - return Err(format!("{at}: two fields are called {}", d.1.id)); - } - groups.push(Group { id: gid, title: gtitle, help: text(g, "help"), fields }); - } - Ok(Controller { id, title, help: text(o, "help"), groups }) -} - -/// A controller from its module's default export as JSON (what `raea spec` prints), checked as `normalize` does. -pub fn of_json(json: &str) -> Result { - normalize(&serde_json::from_str(json).map_err(|e| e.to_string())?) -} - -/// A value checked against its field: the same type, a choice among its options, a number within its range. The -/// value as it's kept (a workflow's steps filled in, a list's strings trimmed). -pub fn check_value(f: &Field, v: &Value) -> Result { - let w = &f.label; - match &f.kind { - Kind::Toggle { .. } => v.as_bool().map(Value::Bool).ok_or_else(|| format!("{w} is on or off: true or false")), - Kind::Choice { options, .. } => v.as_str().filter(|s| options.iter().any(|o| o == s)).map(|s| Value::String(s.into())).ok_or_else(|| format!("{w} is one of: {}", options.join(", "))), - Kind::Number { min, max, .. } => { - let n = v.as_f64().filter(|n| n.is_finite()).ok_or_else(|| format!("{w} is a number"))?; - if min.is_some_and(|m| n < m) || max.is_some_and(|m| n > m) { - let (lo, hi) = (min.map_or("-∞".into(), |m| m.to_string()), max.map_or("∞".into(), |m| m.to_string())); - return Err(format!("{w} is between {lo} and {hi}")); - } - Ok(v.clone()) - } - Kind::Text { .. } => v.as_str().map(|s| Value::String(s.into())).ok_or_else(|| format!("{w} is text")), - Kind::Workflow { .. } => Ok(serde_json::to_value(steps(Some(v), w)?).unwrap_or_default()), - _ => Ok(serde_json::to_value(strings(Some(v), w)?).unwrap_or_default()), - } -} - -/// The field at a path (controller.group.field) among the controllers. -pub fn field<'a>(cs: &'a [Controller], path: &str) -> Option<&'a Field> { - let mut p = path.splitn(3, '.'); - let (c, g, f) = (p.next()?, p.next()?, p.next()?); - cs.iter().find(|x| x.id == c)?.groups.iter().find(|x| x.id == g)?.fields.iter().find(|x| x.id == f) -} diff --git a/core/brief/src/lib.rs b/core/brief/src/lib.rs index b0a1c96b8..1af26aa82 100644 --- a/core/brief/src/lib.rs +++ b/core/brief/src/lib.rs @@ -4,13 +4,11 @@ //! types (`declarations`), so what tsc checks is exactly what this crate reads. pub mod brief; -pub mod controller; pub mod plan; pub mod script; pub mod taste; pub use brief::Brief; -pub use controller::Controller; pub use plan::Plan; pub use script::Script; pub use taste::Taste; @@ -36,9 +34,8 @@ pub fn declarations() -> String { out.extend(decls!(cfg; brief::Brief, brief::Section, brief::Deliverable, brief::Reference, brief::Stage, brief::Mark, brief::Task, brief::Agent, script::Script, script::Scene, script::Beat, script::Line, - taste::Taste, taste::TasteSection, taste::Rule, taste::Check, + taste::Taste, taste::TasteSection, taste::Rule, taste::RuleCheck, taste::RuleLevel, taste::Check, plan::Plan, plan::Concept, plan::Level, plan::Count, plan::Part, - controller::Controller, controller::Group, controller::Field, controller::Kind, controller::Step, )); out.join("\n\n") + "\n" } diff --git a/core/brief/src/taste.rs b/core/brief/src/taste.rs index 4d588dfb0..9b7ac9385 100644 --- a/core/brief/src/taste.rs +++ b/core/brief/src/taste.rs @@ -1,7 +1,10 @@ //! A person's taste: standing corrections kept across every project, read by every agent before any work. A rule is -//! words; a rule that's mechanical also carries a check, a typed value `raea check --taste` holds every export to. +//! words; a rule that's mechanical also carries a check `raea check` holds the work to: one of six typed forms, any of +//! raea's checks by name, or a project's own `.ts` check by its path from the taste file (docs/direction.feature DR4). +//! The person's taste, a workspace's and a project's are read the same way. -use serde::{Deserialize, Serialize}; +use serde::{Deserialize, Deserializer, Serialize}; +use serde_json::{Map, Value}; use ts_rs::TS; #[derive(Debug, Clone, PartialEq, Serialize, Deserialize, TS)] @@ -34,7 +37,52 @@ pub struct TasteSection { #[ts(optional_fields)] pub struct Rule { pub text: String, - pub check: Option, + pub check: Option, + /// what a named or a .ts check is held to (`{ band: 0.8 }`); a form carries its own value + #[ts(type = "Record", optional)] + pub values: Option>, + /// how bad what its check finds is: error, warn or note (unset: a form's findings are errors, another check's keep + /// its own level) + pub level: Option, +} + +#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize, TS)] +#[serde(rename_all = "lowercase")] +pub enum RuleLevel { + Error, + Warn, + Note, +} + +/// What holds a line: one of the six forms raea measures on an export (`{ form: "text-above", value: 75 }`), or a +/// check by name (one of raea's, `"loudness"`) or by path (the project's own, `"../checks/cut.ts"`, written with +/// raea/check), held to the line's `values`. +#[derive(Debug, Clone, PartialEq, Serialize, TS)] +#[serde(untagged)] +pub enum RuleCheck { + Form(Check), + Named(String), +} + +impl<'de> Deserialize<'de> for RuleCheck { + // a name is a string; anything else is a form, and a wrong one says what was wrong with it (not "no variant") + fn deserialize>(d: D) -> Result { + match Value::deserialize(d)? { + Value::String(s) if !s.trim().is_empty() => Ok(RuleCheck::Named(s)), + Value::String(_) => Err(serde::de::Error::custom("a check's name or path is empty")), + v => Check::deserialize(v).map(RuleCheck::Form).map_err(serde::de::Error::custom), + } + } +} + +impl RuleCheck { + /// The form, when it is one of the six. + pub fn form(&self) -> Option { + match self { + RuleCheck::Form(c) => Some(*c), + RuleCheck::Named(_) => None, + } + } } /// What a check measures on an export. Values keep the units the checker has always used. @@ -75,8 +123,8 @@ impl Check { } impl Taste { - /// Every rule that carries a check, with its words. + /// Every rule that carries one of the six forms, with its words (what `raea check VIDEO.mp4` measures). pub fn checks(&self) -> impl Iterator { - self.sections.iter().flat_map(|s| s.rules.iter()).filter_map(|r| r.check.map(|c| (r.text.as_str(), c))) + self.sections.iter().flat_map(|s| s.rules.iter()).filter_map(|r| r.check.as_ref()?.form().map(|c| (r.text.as_str(), c))) } } diff --git a/core/brief/src/tests.rs b/core/brief/src/tests.rs index 742cc6cf6..ce6e06e6f 100644 --- a/core/brief/src/tests.rs +++ b/core/brief/src/tests.rs @@ -51,6 +51,22 @@ fn taste_checks_are_typed_values() { assert!(read::("motion.ts", r#"{"title": "t", "sections": [{"heading": "h", "rules": [{"text": "x", "check": {"form": "glow-max", "value": 1}}]}]}"#).is_err()); } +#[test] +fn a_taste_line_holds_any_check_by_name_or_path_with_values_and_a_level() { + let t: Taste = read("taste.ts", r#"{"title": "Proof", "sections": [{"heading": "Rules", "rules": [ + {"text": "Captions clear the button band", "check": "../checks/caption.ts", "values": {"band": 0.8}, "level": "warn"}, + {"text": "Loud enough", "check": "loudness", "values": {"value": -14}}]}]}"#).unwrap(); + let r = &t.sections[0].rules; + assert_eq!((r[0].check.as_ref(), r[0].values.as_ref().and_then(|v| v["band"].as_f64()), r[0].level), (Some(&taste::RuleCheck::Named("../checks/caption.ts".into())), Some(0.8), Some(taste::RuleLevel::Warn))); + assert_eq!(t.checks().count(), 0, "only the six forms are what a video's check measures"); + // it reads back as written, and a wrong level or an empty name says what's wrong + assert_eq!(read::("taste.ts", &serde_json::to_string(&t).unwrap()).unwrap(), t); + let bad = |rule: &str| read::("taste.ts", &format!(r#"{{"title": "t", "sections": [{{"heading": "h", "rules": [{rule}]}}]}}"#)).unwrap_err(); + assert!(bad(r#"{"text": "x", "check": "cut.ts", "level": "warning"}"#).contains("expected one of `error`, `warn`, `note`")); + assert!(bad(r#"{"text": "x", "check": ""}"#).contains("empty")); + assert!(bad(r#"{"text": "x", "check": {"form": "text-above", "value": "high"}}"#).contains("invalid type")); +} + #[test] fn a_plan_leaves_nothing_without_a_material() { let ok: Plan = read("plan.ts", r#"{"concept": {"what": "flight feather", "style": "realistic", "size": 0.25, "seenFrom": 0.3, "material": "keratin"}, @@ -75,59 +91,3 @@ fn a_close_view_needs_tertiary_detail() { "parts": {"body": {"role": "body", "level": "primary"}, "rocker": {"role": "rocker", "level": "secondary", "parent": "body", "count": 2}}}"#).unwrap(); assert!(plan::check(&p).iter().any(|m| m.contains("tertiary"))); } - -const DELIVERY: &str = r#"{"title": "Delivery", "help": "What every final keeps", "groups": [{"title": "Format", "fields": [ - {"label": "Aspect ratio", "type": "choice", "options": ["9:16", "4:5", "1:1"], "value": "9:16"}, - {"label": "Loudness", "type": "number", "value": -14, "unit": "LUFS", "min": -30, "max": 0}, - {"label": "Burn in captions", "type": "toggle", "value": true}, - {"label": "Steps", "type": "workflow", "value": [{"name": "Cut", "by": "@cutter"}, {"name": "Review", "by": "you", "back": "Cut"}]}]}]}"#; - -#[test] -fn a_controller_fills_ids_from_titles_and_labels() { - let c = controller::normalize(&serde_json::from_str(DELIVERY).unwrap()).unwrap(); - assert_eq!(c.id, "delivery"); - assert_eq!(c.groups[0].id, "format"); - let ids: Vec<_> = c.groups[0].fields.iter().map(|f| f.id.as_str()).collect(); - assert_eq!(ids, ["aspect-ratio", "loudness", "burn-in-captions", "steps"]); - let controller::Kind::Workflow { value, .. } = &c.groups[0].fields[3].kind else { panic!("a workflow") }; - assert_eq!(value[0].by.as_deref(), Some("cutter")); - // what it writes back reads as the same controller (the page's types are these) - let again = controller::normalize(&serde_json::to_value(&c).unwrap()).unwrap(); - assert_eq!(again, c); -} - -#[test] -fn a_controller_says_what_is_wrong_in_a_sentence_the_agent_can_act_on() { - let bad = |j: &str| controller::normalize(&serde_json::from_str(j).unwrap()).unwrap_err(); - assert!(bad(r#"{"title": "X", "groups": [{"title": "G", "fields": [{"label": "A", "type": "slider"}]}]}"#).contains("type must be one of")); - assert!(bad(r#"{"title": "X", "groups": [{"title": "G", "fields": [{"label": "A", "type": "choice", "options": ["one"]}]}]}"#).contains("at least two options")); - assert!(bad(r#"{"title": "X"}"#).contains("needs groups")); - assert!(bad(r#"{"groups": []}"#).contains("needs a title")); - assert!(bad(r#"{"title": "X", "groups": [{"title": "G", "fields": [{"label": "A", "type": "toggle"}, {"label": "a", "type": "toggle"}]}]}"#).contains("two fields are called a")); - assert!(bad(r#"{"title": "X", "groups": [{"title": "G", "fields": [{"label": "A", "type": "rule"}]}]}"#).contains("a rule needs a check")); - assert!(bad(r#"{"title": "X", "groups": [{"title": "G", "fields": [{"label": "A", "type": "rule", "check": "x", "level": "p0"}]}]}"#).contains("error, warn or note")); -} - -#[test] -fn a_rule_field_is_a_check_by_name_with_values_or_a_path() { - let j = r#"{"title": "Rules", "groups": [{"title": "Vertical", "fields": [ - {"label": "Captions clear the button band", "type": "rule", "check": "./checks/clear.ts", "values": {"platform": "tiktok"}, "level": "warn"}, - {"label": "Words stay up long enough to read", "type": "rule", "check": "text-hold", "values": {"value": 1.5}}]}]}"#; - let c = controller::normalize(&serde_json::from_str(j).unwrap()).unwrap(); - let controller::Kind::Rule { check, values, level } = &c.groups[0].fields[0].kind else { panic!("a rule") }; - assert_eq!((check.as_str(), level.as_deref()), ("./checks/clear.ts", Some("warn"))); - assert_eq!(values.as_ref().unwrap()["platform"], "tiktok"); - assert_eq!(controller::normalize(&serde_json::to_value(&c).unwrap()).unwrap(), c, "it reads back as written"); -} - -#[test] -fn a_value_is_checked_against_its_field() { - let c = controller::normalize(&serde_json::from_str(DELIVERY).unwrap()).unwrap(); - let cs = [c]; - let f = |p: &str| controller::field(&cs, p).unwrap(); - assert!(controller::check_value(f("delivery.format.loudness"), &serde_json::json!(-16)).is_ok()); - assert!(controller::check_value(f("delivery.format.loudness"), &serde_json::json!(4)).unwrap_err().contains("between -30 and 0")); - assert!(controller::check_value(f("delivery.format.aspect-ratio"), &serde_json::json!("16:9")).unwrap_err().contains("one of: 9:16, 4:5, 1:1")); - assert!(controller::check_value(f("delivery.format.burn-in-captions"), &serde_json::json!("yes")).is_err()); - assert!(controller::field(&cs, "delivery.format.nope").is_none()); -} diff --git a/core/facts/Cargo.toml b/core/facts/Cargo.toml index 5aace12e2..529bd8a4f 100644 --- a/core/facts/Cargo.toml +++ b/core/facts/Cargo.toml @@ -8,7 +8,7 @@ description = "A project as one world of facts in raea/ecs's form: its layers, t [dependencies] dunce = "1" -# a rule's taste form and controller field (rule.rs) +# a taste line and its check, as a rule (rule.rs) raea-core-brief = { path = "../brief" } serde = { version = "1", features = ["derive"] } serde_json = "1" diff --git a/core/facts/src/rule.rs b/core/facts/src/rule.rs index 2886d83b7..7fcfd819d 100644 --- a/core/facts/src/rule.rs +++ b/core/facts/src/rule.rs @@ -1,12 +1,12 @@ //! A rule: a line the work is held to, and the check that holds it (docs/direction.feature DR4). The check is one of //! raea's, by name with its values (apps/direction systems.rs), or a project's own TS check by its path (sdk/raea -//! check.ts). Where a rule was written (raea's floor, the person's taste, a workspace's or a project's controller) +//! check.ts). Where a rule was written (raea's floor, the person's, a workspace's or a project's taste file) //! changes nothing about how it runs: it is only said, as its findings' `by`. A taste file's six forms are six of //! raea's named checks with the same names and values, so every taste file reads as it did. use std::path::Path; -use raea_core_brief::{controller, taste}; +use raea_core_brief::taste; use serde::{Deserialize, Serialize}; use serde_json::{Map, Value}; @@ -49,32 +49,33 @@ impl Rule { self.values.get(name).and_then(Value::as_f64) } - /// A taste line that carries a check: the named check of its form (text-hold, text-above, text-below, - /// text-margin, loudness, still-max), its value as `value`. Taste's lines are errors, as raea check held them. - pub fn of_taste(text: &str, c: taste::Check, file: &str) -> Rule { - let values = Map::from_iter([("value".to_string(), Value::from(c.value()))]); - Rule::named(c.form(), text, values, Level::Error, &format!("taste {file}")) - } - - /// A controller's rule fields, each a rule: a check's path joined to `dir` (the controller's folder; its `..` - /// steps are the caller's to take), the field's label its words. `by`: "workspace" or "project", with the - /// controller's file. - pub fn of_controller(c: &controller::Controller, dir: &Path, by: &str) -> Vec { - let mut out = Vec::new(); - for f in c.groups.iter().flat_map(|g| &g.fields) { - let controller::Kind::Rule { check, values, level } = &f.kind else { continue }; - let (check, id) = match check.ends_with(".ts") { - true => { - let path = dir.join(check); - let id = path.file_stem().map(|s| s.to_string_lossy().into_owned()).unwrap_or_default(); - (path.display().to_string(), id) - } - false => (check.clone(), check.clone()), - }; - let level = level.as_deref().map(Level::of_word); - out.push(Rule { id, text: f.label.clone(), check, values: values.clone().unwrap_or_default(), level, by: by.into(), of: None }); + /// A taste line's rule, when it carries a check. One of the six forms is raea's named check of that form, its + /// value as `value`, and an error unless the line says otherwise. A check by name, or by path (joined to `dir`, the + /// taste file's folder; its `..` steps are the caller's to take, and the file's name is the rule's id), is held to + /// the line's `values` at the line's level (unset: the check's own). `by`: "taste" and the file. + pub fn of_taste(r: &taste::Rule, dir: &Path, by: &str) -> Option { + let level = r.level.map(|l| match l { + taste::RuleLevel::Error => Level::Error, + taste::RuleLevel::Warn => Level::Warn, + taste::RuleLevel::Note => Level::Note, + }); + match r.check.as_ref()? { + taste::RuleCheck::Form(c) => { + let values = Map::from_iter([("value".to_string(), Value::from(c.value()))]); + Some(Rule::named(c.form(), &r.text, values, level.unwrap_or(Level::Error), by)) + } + taste::RuleCheck::Named(check) => { + let (check, id) = match check.ends_with(".ts") { + true => { + let path = dir.join(check); + let id = path.file_stem().map(|s| s.to_string_lossy().into_owned()).unwrap_or_default(); + (path.display().to_string(), id) + } + false => (check.clone(), check.clone()), + }; + Some(Rule { id, text: r.text.clone(), check, values: r.values.clone().unwrap_or_default(), level, by: by.into(), of: None }) + } } - out } } @@ -82,23 +83,24 @@ impl Rule { mod tests { use super::*; + fn line(j: serde_json::Value) -> taste::Rule { + serde_json::from_value(j).unwrap() + } + #[test] fn a_taste_form_is_the_named_check_of_the_same_name_and_value() { - let r = Rule::of_taste("Captions sit clear of the bottom.", taste::Check::TextAbove(62.0), "taste.ts"); + let r = Rule::of_taste(&line(serde_json::json!({"text": "Captions sit clear of the bottom.", "check": {"form": "text-above", "value": 62}})), Path::new("/p"), "taste taste.ts").unwrap(); assert_eq!((r.id.as_str(), r.check.as_str(), r.number("value"), r.level), ("text-above", "text-above", Some(62.0), Some(Level::Error))); assert!(r.file().is_none() && r.by == "taste taste.ts"); + assert!(Rule::of_taste(&line(serde_json::json!({"text": "The look is neutral."})), Path::new("/p"), "taste taste.ts").is_none(), "words alone hold nothing"); } #[test] - fn a_controllers_rule_fields_are_rules_and_a_path_is_from_its_folder() { - let raw = serde_json::json!({"title": "Rules", "groups": [{"title": "G", "fields": [ - {"label": "Captions clear the button band", "type": "rule", "check": "../checks/clear.ts", "level": "warn"}, - {"label": "Loud enough", "type": "rule", "check": "loudness", "values": {"value": -14}}, - {"label": "Burn in captions", "type": "toggle", "value": true}]}]}); - let c = controller::normalize(&raw).unwrap(); - let rs = Rule::of_controller(&c, Path::new("/p/controllers"), "project controllers/rules.ts"); - assert_eq!(rs.len(), 2, "a toggle is no rule"); - assert_eq!((rs[0].id.as_str(), rs[0].file(), rs[0].level), ("clear", Some(Path::new("/p/controllers/../checks/clear.ts")), Some(Level::Warn))); - assert_eq!((rs[1].check.as_str(), rs[1].number("value"), rs[1].level), ("loudness", Some(-14.0), None)); + fn a_taste_lines_check_by_path_is_from_its_folder_and_by_name_keeps_its_values() { + let clear = line(serde_json::json!({"text": "Captions clear the button band", "check": "../checks/clear.ts", "level": "warn"})); + let r = Rule::of_taste(&clear, Path::new("/p/sub"), "taste sub/taste.ts").unwrap(); + assert_eq!((r.id.as_str(), r.file(), r.level), ("clear", Some(Path::new("/p/sub/../checks/clear.ts")), Some(Level::Warn))); + let loud = Rule::of_taste(&line(serde_json::json!({"text": "Loud enough", "check": "loudness", "values": {"value": -14}})), Path::new("/p"), "taste taste.ts").unwrap(); + assert_eq!((loud.check.as_str(), loud.number("value"), loud.level), ("loudness", Some(-14.0), None)); } } diff --git a/docs/direction.feature b/docs/direction.feature index 1ff939768..9904e9ad9 100644 --- a/docs/direction.feature +++ b/docs/direction.feature @@ -100,8 +100,8 @@ Feature: Direction that holds: one world of facts, findings and rules, so a pers 4. A check is code where the ask can be measured, and a named clip the person signs where it can't; it says which. A row with a still is neither. 5. Rounds hold. Every earlier round's checks run in every later round; a regression names the note it breaks. - 6. A rule climbs: a note's check, kept for the project, becomes a project rule (a controller); kept across - projects, the person's taste. It is the same check at each level, moved, never rewritten. + 6. A rule climbs: a note's check, kept for the project, becomes a project rule (a line in its taste.ts); kept + across projects, the person's taste. It is the same check at each level, moved, never rewritten. 7. The order of work is components, blocking, look, cameras, sound, each reviewed before the next. A later stage is refused on a failing earlier one. 8. Every prop is a component whose typed props are its rig, and which says what it is and where it belongs. @@ -116,7 +116,7 @@ Feature: Direction that holds: one world of facts, findings and rules, so a pers Background: Given the raea skill is raea-skills' (the skills/ submodule); a change to it is a raea-skills PR and a pin bump - And a project is a folder in raea's format (projects.feature), its workspace's controllers in controllers/ + And a project is a folder in raea's format (projects.feature), its rules in its own and its workspace's taste.ts And raea/ecs is the format: `spawn(components)`, `find({ with, without, where })`, relations as components, resources by name, a system `(world, frame) => void`, `world.at(frame)` the same whenever it's asked for @@ -142,6 +142,8 @@ Feature: Direction that holds: one world of facts, findings and rules, so a pers its values or a path to a project check; a project rule is a controller with rule fields # Fixed in the code (DR4): the field's words are its `label`, as every controller field's are, and its values are # a field of their own: `{ label, type: "rule", check, values?, level? }`. + # 11-20 (projects.feature PJ9): controllers are gone; a rule is a taste line `{ text, check, values?, level? }`, + # its check one of the six forms, a name or a path, in the person's, the workspace's or the project's taste.ts. And the taste file's six forms become six of raea's named checks (same names, same values), so `{ form: "text-above", value: 62 }` still reads and no taste file changes And the stages are recorded in .raea/project (`[stage] components = passed ` ...), set by the stage's @@ -334,6 +336,9 @@ Feature: Direction that holds: one world of facts, findings and rules, so a pers @needs:DR1,DR3 @done Scenario: DR4. A check is a system; raea's own are written the same way + # 11-20 (projects.feature PJ9): the rules come from the taste files alone (the person's, the workspace's and now the + # project's own); a taste line holds what a controller's rule field held, and bench/direction/proof's rules are its + # taste.ts's lines. # Status 11-10: built. A rule is a line and the check that holds it (core/facts rule.rs): one of raea's checks by # name with its values, or a project's .ts check by its path. A controller field of type `rule` ({ label, check, # values?, level? }) is one; taste's six forms are six named checks with the same names and values. `raea check @@ -593,13 +598,14 @@ Feature: Direction that holds: one world of facts, findings and rules, so a pers # Fixed in the code (DR4): the field type `rule` and reading rule fields as checks were planned here # (rule_field.rs, and rules.rs's first job). `raea check` needed both to run a project's rules, so DR4 built them: # Kind::Rule in core/brief controller.rs, and the rules read in apps/direction check.rs. - Then `raea notes keep` moves a note's check to controllers/.ts as a rule field (project or workspace), or - to the person's taste as a rule; the note keeps a pointer; the check's text is not copied + # 11-20 (projects.feature PJ9): controllers are gone, so a kept check becomes a taste line, and the rules that + # apply are listed by `raea check --json` and the app's rules_read, not a controller verb. + Then `raea notes keep` moves a note's check to a line in a taste.ts (the project's, the workspace's or the + person's), its check named by path; the note keeps a pointer; the check's text is not copied And the taste loop (docs/craft-system.md J) proposes this when a correction repeats, as it does now, and now for any check, not six forms - And a rule's field (a limit, a list of kinds) is edited in the app's Controllers page like any field, and the - check reads it: "how do controllers become rules" is this - And `raea controller ls --rules` lists every rule that applies to a project and where it came from + And a rule's values (a limit, a list of kinds) are edited in its taste line, and the check reads them: "how do + rules get made" is this @needs:DR6 Scenario: DR9. A check that can be gamed is found before it's trusted @@ -717,9 +723,9 @@ Feature: Direction that holds: one world of facts, findings and rules, so a pers Rule: Part 6. A look of the project's own (finding 2) @needs:DR10 - Scenario: DR18. The project's look is a file in the project, with its controller + Scenario: DR18. The project's look is a file in the project, with its props Given shaders.feature SH4 (``: one shader over every lit surface of a scene) and frame passes - Then looks/.wesl is the project's shading, and looks/.ts its controller: the uniforms as fields + Then looks/.wesl is the project's shading, and looks/.ts its props: the uniforms as typed props (colours, ramps, widths), so a look is tuned in the app and animated like any rig And `` puts it on a scene; the look stage's review is one scene from blocking under it, in a clip, beside the brief's references @@ -731,7 +737,7 @@ Feature: Direction that holds: one world of facts, findings and rules, so a pers @needs:DR18 Scenario: DR24. A worked project look, from what was written on 11-10 Then the gradient light, the world cuts (a mesh drawn only inside its ball, in the main pass and the prepass) - and the nine styles are an example project look under examples/, on SurfaceShader, with its controller + and the nine styles are an example project look under examples/, on SurfaceShader, with its props And the stock paint look is as it was before 11-10; the camera columns a continuous render refreshes each frame (runtime/scene/src/live.rs cam_keyed) take a look's declared uniforms, not a list of names diff --git a/docs/ecosystem.feature b/docs/ecosystem.feature index eecf8d16b..129d9da9e 100644 --- a/docs/ecosystem.feature +++ b/docs/ecosystem.feature @@ -24,7 +24,7 @@ Feature: raea's plugin ecosystem: extending the engine and the app, made, shared - The Plugins page is a fixed catalog of integrations (src/plugins/catalog.ts): ACP agents, accounts on networks, keyed generation services. Its entries are connections, not code. - The app's extension points today are data and agents: any ACP agent, the feed tools an agent calls - (feed_post, controller_write, item_tags...), controllers as TypeScript files, and artifacts: since 11-09 (phase + (feed_post, rule_add, item_tags...), taste files as TypeScript, and artifacts: since 11-09 (phase 1, EC12) an agent's own React file, posted with feed_post, built by the host and run in a sandboxed frame that talks to the app only through @raea/app (apps/app host/artifact.ts, src/artifacts/). @@ -107,7 +107,7 @@ Feature: raea's plugin ecosystem: extending the engine and the app, made, shared Then the app runs each extension in a sandboxed frame of its own (as an artifact runs now: scripts, no same origin), never in the app's own JS realm, so it can't read keys, call /host/* or touch another extension And it talks to the app through `@raea/app`, a typed bridge over postMessage: read the project, the feed and an - item; read and write comments and pins; post items; read and write controllers; call raea's CLI verbs the + item; read and write comments and pins; post items; read the taste and add a rule; call raea's CLI verbs the manifest's permissions allow; open views; show a notice And every bridge call is checked against the permissions the person approved, and refused with which permission it lacked diff --git a/docs/hardware.feature b/docs/hardware.feature index 1554bcf83..767f45389 100644 --- a/docs/hardware.feature +++ b/docs/hardware.feature @@ -96,6 +96,8 @@ Feature: Hardware: controls that feel like instruments, heard on raea's own mixe Rule: HW3. Where the kit is used Scenario: HW3a. Controllers + # 11-20 (projects.feature PJ9): controllers are gone, so this has no page to land on; the kit's controls are + # Settings' (HW3b) and the editor's. Then a controller's fields are the kit's: a toggle is a switch, a choice a segmented selector (a dial past five options), a number a knob or a fader with its readout, and each change sounds as it is made diff --git a/docs/layout.feature b/docs/layout.feature index a2fe37421..595fb3ab0 100644 --- a/docs/layout.feature +++ b/docs/layout.feature @@ -1,4 +1,4 @@ -Feature: One project layout: compositions, components, controllers, assets, artifacts; and the workspace's shared/ +Feature: One project layout: compositions, components, assets, artifacts; and the workspace's shared/ Shane, 11-12: "reorganize the default project organization to remove "parts" and really align around the folders of compositions, components, controllers, assets, artifacts. this should be the default, and at the workspace level having a library that any project can call upon from those global folders." On naming: "just make sure it doesn't @@ -23,26 +23,28 @@ Feature: One project layout: compositions, components, controllers, assets, arti app pages (Compositions, Controllers, Source), LY4's examples/components rename and the guides and skill wording, LY5 (`raea project tidy`), LY6. + 11-20 (projects.feature PJ9): controllers are gone, so a new project or shared/ has four folders, not five, and a + project's or workspace's rules are its taste.ts. The lines below that name controllers are kept as they were planned. + The layout: / .raea/workspace, taste.ts, projects/, attachments/ as now shared/ what every project in the workspace can call on - compositions/ components/ controllers/ assets/ artifacts/ + compositions/ components/ assets/ artifacts/ /projects// .raea/project, brief.ts, .script.ts, AGENTS.md what the project is (as now, at its root) compositions/ what renders: a registerRoot , or a default export; versions NAME-v2.tsx components/ what compositions import: props as rigs (component-library-first), raea's sets - controllers/ the project's controllers (PJ2), over shared/controllers/ by id assets/ media in: footage, stills, audio, models, fonts, the brand kit (assets/brand/) artifacts/ the small React apps agents post to the feed out/ renders (LFS, as now) Scenario: LY1. A new project and a new workspace have the layout When `raea project new NAME` makes a project - Then its folder has compositions/, components/, controllers/, assets/ and artifacts/ (each kept with a .gitkeep), + Then its folder has compositions/, components/, assets/ and artifacts/ (each kept with a .gitkeep), out/, brief.ts and AGENTS.md, and no media/, brand/ or parts/ - And `raea workspace init` makes shared/ with the same five folders, and no root controllers/ or artifacts/ + And `raea workspace init` makes shared/ with the same four folders, and no root controllers/ or artifacts/ And .gitattributes keeps assets/** and out/** in LFS (shared/assets/** too) And AGENTS.md says where each kind of file goes, in a line each, and that @shared/ is the workspace's And `raea init` in a loose folder makes compositions/edit.tsx and components/, not edit.tsx at the root @@ -64,12 +66,10 @@ Feature: One project layout: compositions, components, controllers, assets, arti with @shared/ as the fix when the file is in shared/ Scenario: LY3. One reading of the layout, everywhere - When `raea project scan`, the app's Compositions, Controllers and Source pages, and `raea context` read a project + When `raea project scan`, the app's Compositions and Source pages, and `raea context` read a project Then compositions come from compositions/ and components from components/, each also from shared/ (marked shared) And a .tsx elsewhere in the project is still read by what it is (PJ8), and linted as out of place with the folder it belongs in as the fix - And controllers are the project's controllers/ over shared/controllers/ by id (a project's own wins), so the 11-07 - per-project copy is no longer needed: `raea controller ls` says which are shared And Source's Assets tab lists assets/ (and shared/assets/), and its Artifacts tab artifacts/ (and shared/artifacts/) And an agent's feed_post of an artifact writes it to the project's artifacts/ @@ -84,7 +84,7 @@ Feature: One project layout: compositions, components, controllers, assets, arti When `raea project tidy [NAME] [--dry-run]` runs on a project in the old layout Then each file goes where its kind belongs, as the scan reads it: compositions (and their versions) to compositions/, the .tsx they import to components/ (parts/ and its subfolders as components/), - controllers to controllers/, media/ and brand/ to assets/ (assets/brand/), artifacts to artifacts/ + media/ and brand/ to assets/ (assets/brand/), artifacts to artifacts/ And brief.ts, scripts, notes (.md) and out/ stay where they are; anything it can't place is listed, not moved And every import that names a moved file is rewritten (relative paths, media imports), and so are the paths the project's feed items, render manifests and checks name @@ -92,7 +92,7 @@ Feature: One project layout: compositions, components, controllers, assets, arti And it proves the move before it commits: the scan has no new lint, tsc passes if it passed before, and each composition's first frame renders as it did (raea check --quick); a failure undoes the move And it is one commit per project, moves as renames (git mv), so history follows each file - And the workspace's root controllers/ and artifacts/ move to shared/ the same way (`raea workspace tidy`) + And the workspace's root artifacts/ move to shared/ the same way (`raea workspace tidy`) Scenario: LY6. The Raea workspace is tidied Given the Raea workspace (~/Documents/raea/raea): stay, orientation, v0-1-launch and two untitled projects diff --git a/docs/manual/concepts/workspaces.md b/docs/manual/concepts/workspaces.md index 248556c2b..5b09a594e 100644 --- a/docs/manual/concepts/workspaces.md +++ b/docs/manual/concepts/workspaces.md @@ -1,6 +1,6 @@ --- title: "Workspaces and projects" -summary: "Where work lives in raea: a workspace is a git repository of projects and controllers, and each project has a brief and folders for media and renders." +summary: "Where work lives in raea: a workspace is a git repository of projects, and each project has a brief, its taste and folders for media and renders." order: 3 sources: ["apps/workspace/src", "core/brief/src", "skills/skills/raea/reference/files.md"] --- @@ -11,7 +11,7 @@ and where the files go. ## A workspace -A workspace is a git repository, one per studio or client, that holds projects and controllers. Workspaces live under +A workspace is a git repository, one per studio or client, that holds projects and their house taste. Workspaces live under your raea root, which is `~/Studio` unless you set another: ```sh @@ -55,8 +55,8 @@ raea's specs are TypeScript files whose default export is checked against a sche | `brief.ts` | The project's brief | | `NAME.script.ts` | A storyboard: scenes of beats, what's on screen, what each scene must land | | `~/.raea/taste/taste.ts` | The person's taste, which beats any guide's default | +| `taste.ts` | A workspace's or a project's rules, which `raea check` holds every piece to | | `plan.ts` | A frozen plan for a build, checked by raea | -| `controllers/ID.ts` | The workspace's settings and workflows | ```sh raea spec brief.ts # prints the brief as JSON, checked against its schema @@ -80,15 +80,23 @@ export default brief({ The full list of each spec's fields is in [Files and specs](../reference/files.md). -## Controllers +## Rules -Controllers are the workspace's settings and workflows: delivery specs, who reviews what, the tools every agent gets. -Every change to one is a git commit. +A standing decision ("every ad is 9:16", "captions clear the button band") is a line in a taste file: the person's +(`~/.raea/taste/taste.ts`), the workspace's or the project's own `taste.ts`. A line raea can measure carries a check: +one of raea's by name, or the project's own `.ts` check, and `raea check` holds every piece to it. -```sh -raea controller ls # every controller, with its groups and fields -raea controller get CONTROLLER.GROUP.FIELD # one value -raea controller set CONTROLLER.GROUP.FIELD VALUE # change it, as a commit +```ts +import { taste } from "raea/brief"; + +export default taste({ + title: "Acme's rules", + sections: [{ heading: "Delivery", rules: [ + { text: "Every ad is 9:16." }, + { text: "Captions sit above three quarters of the frame.", check: { form: "text-above", value: 75 } }, + { text: "Loud enough for a phone.", check: "loudness", values: { value: -14 } }, + ] }], +}); ``` ## Reading a project before working on it @@ -98,5 +106,5 @@ raea context . ``` prints, in order, everything an agent should read before making anything in the project: the person's taste, the -workspace's taste, the brief, the look, the controllers, the craft floor and the guides for the brief's modes. See +workspace's taste, the project's taste, the brief, the look, the craft floor and the guides for the brief's modes. See [How an agent should use raea](../start/agents.md). diff --git a/docs/manual/reference/cli/add.md b/docs/manual/reference/cli/add.md index b1bce44a3..a1ae04ad6 100644 --- a/docs/manual/reference/cli/add.md +++ b/docs/manual/reference/cli/add.md @@ -1,7 +1,7 @@ --- title: "raea add" summary: "Add, remove and install npm packages for a project, with no Node or npm: raea.lock and node_modules." -order: 29 +order: 28 sources: ["io/npm/src/lib.rs"] --- diff --git a/docs/manual/reference/cli/brand.md b/docs/manual/reference/cli/brand.md index 4817076d8..81133bbc5 100644 --- a/docs/manual/reference/cli/brand.md +++ b/docs/manual/reference/cli/brand.md @@ -1,7 +1,7 @@ --- title: "raea brand" summary: "Read a brand kit from a website on this machine: colours, fonts and logos into brand/ and BRAND.md." -order: 30 +order: 29 sources: ["engine/cli/src/brand.ts", "engine/cli/src/scrape.ts"] --- diff --git a/docs/manual/reference/cli/check.md b/docs/manual/reference/cli/check.md index 33bd904e9..ff37cf15d 100644 --- a/docs/manual/reference/cli/check.md +++ b/docs/manual/reference/cli/check.md @@ -30,9 +30,9 @@ each an error when broken, since their rule beats the floor's default. ## Every rule a project holds On a project, or a composition's file, with no `--quick`, `raea check` runs every rule that applies to each -composition: raea's floor on its newest render, your taste's measurable lines, and the rules in the workspace's and -the project's controllers. A rule is a controller field of type `rule`: its words, and the check that holds it, -either one of raea's by name with its values or a `.ts` check of your own. +composition: raea's floor on its newest render, and every line with a check in your taste, the workspace's +`taste.ts` and the project's own. A rule is such a line: its words, and the check that holds it, one of raea's six +measured forms, one of raea's checks by name with its values, or a `.ts` check of your own by its path. raea's reading check, `text-read`, runs on the newest render too, with nothing asking for it. Each text's reading time (0.3 s a word, at least a second) is held to the frames it can be read on (in the frame, at an opacity, size and @@ -41,8 +41,8 @@ Text that can be read where OCR doesn't read it is an error: it's broken. Render text is counted. ```ts -// controllers/rules.ts -{ label: "Captions clear the button band", type: "rule", check: "../checks/caption.ts", values: { band: 0.8 } } +// taste.ts, in the project +{ text: "Captions clear the button band", check: "checks/caption.ts", values: { band: 0.8 } } ``` A check is a system over the composition's world, the same world `raea world` prints, so it reads a caption, a @@ -72,7 +72,7 @@ last change is still joined, with a note that what it measured may have moved. ```sh raea check EDIT.tsx --quick [--shape S] [--platform P] [--taste T] [-o check.json] (three stills of a composition checked for text: clipped, cramped, safe areas, sizes; about a second) -raea check [PROJECT|EDIT.tsx] [--composition ID] [--only ID] [--taste T] [--render OUT | --no-render] [--json] (every check that applies to each composition, over its frames: raea's floor on its newest render, the person's taste, the workspace's and the project's rules (a controller's rule fields: one of raea's checks by name, or a project's .ts check); what needs a render and has none waits, and says so) +raea check [PROJECT|EDIT.tsx] [--composition ID] [--only ID] [--taste T] [--render OUT | --no-render] [--json] (every check that applies to each composition, over its frames: raea's floor on its newest render, the person's, the workspace's and the project's taste.ts (each line's check: one of raea's forms or checks by name, or a project's .ts check); what needs a render and has none waits, and says so) raea check VIDEO.mp4 [--manifest render.json] [--words W.json] [--perception P.json] [--things T.json] [--shape 16:9|9:16|4:5|1:1] [--platform tiktok|reels|shorts] [--taste taste.ts|DIR] [-o check.json] (an export against the floor: clipped text, contrast, safe areas, freezes, flashing, cues, loudness, blotching, a placeholder brand kit, and with --things what `raea fingerprint things --json` found: a thing floating or passing through another, the camera lurching mid-move, an empty frame; its findings errors, warns and notes) ``` diff --git a/docs/manual/reference/cli/component.md b/docs/manual/reference/cli/component.md index a26ec2ba9..269b423bf 100644 --- a/docs/manual/reference/cli/component.md +++ b/docs/manual/reference/cli/component.md @@ -1,7 +1,7 @@ --- title: "raea component" summary: "Copy a ready-made component or set into the project's components/, or the workspace's shared/components/, to use and change as your own." -order: 27 +order: 26 sources: ["engine/cli/src/index.ts", "engine/cli/src/registry.gen.ts"] --- diff --git a/docs/manual/reference/cli/controller.md b/docs/manual/reference/cli/controller.md deleted file mode 100644 index b9db83724..000000000 --- a/docs/manual/reference/cli/controller.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: "raea controller" -summary: "Read and change the workspace's controllers: its settings and workflows, each a TypeScript file." -order: 25 -sources: ["apps/workspace/src/controllers.rs"] ---- - -Controllers are a workspace's settings and workflows, each `controllers/ID.ts` exporting `controller({...})` from -`raea/brief`. A field is named by its path, `controller.group.field`. A project can override a field for itself, -and its value then wins, as git config's scopes do. Every change is a commit, by "you" unless `--by` names someone. - -```sh -raea controller ls -raea controller get delivery.format.aspect-ratio -raea controller set delivery.format.aspect-ratio 9:16 --by agent -raea controller set delivery.format.aspect-ratio 16:9 --project # this project only -raea controller write controllers/delivery.ts -raea controller rm delivery -``` - - - -## Usage - -```sh -raea controller ls [--json] | raea controller get PATH [--json] | raea controller set PATH VALUE [--project] [--by NAME] | raea controller write FILE.ts [--by NAME] | raea controller rm ID [--by NAME] (the workspace's controllers, controllers/ID.ts; PATH is controller.group.field; every change a commit) -``` - -Headless: it needs nothing running and opens no window. Takes up to 3 arguments besides its flags. - -## Flags - -| Flag | Takes | What it does | -| --- | --- | --- | -| `--by` | `NAME` | Who made the change, for its commit (`you` by default). An agent passes its own name. | -| `--json` | – | With `ls` and `get`: print JSON instead of text. | -| `--project` | – | With `set`: change the value for the current project only, in its `.raea/project`. | - - diff --git a/docs/manual/reference/cli/index.md b/docs/manual/reference/cli/index.md index c4e151daa..648ffdcf2 100644 --- a/docs/manual/reference/cli/index.md +++ b/docs/manual/reference/cli/index.md @@ -47,10 +47,9 @@ The workspace, its projects and what a project holds. | Verb | What it does | | --- | --- | | [`raea init`](init.md) | Add a project's starting files where they're missing: edit.tsx, cuts.ts, components/ and AGENTS.md. | -| [`raea workspace`](workspace.md) | Make, adopt or show a workspace: the git repository that holds a studio's projects and controllers. | +| [`raea workspace`](workspace.md) | Make, adopt or show a workspace: the git repository that holds a studio's projects and house taste. | | [`raea project`](project.md) | Make a project in the workspace, list them, or move one between inline and a repository of its own. | -| [`raea controller`](controller.md) | Read and change the workspace's controllers: its settings and workflows, each a TypeScript file. | -| [`raea spec`](spec.md) | Print a spec file's default export as JSON, checked against its schema: briefs, scripts, taste, plans and controllers. | +| [`raea spec`](spec.md) | Print a spec file's default export as JSON, checked against its schema: briefs, scripts, taste and plans. | | [`raea component`](component.md) | Copy a ready-made component or set into the project's components/, or the workspace's shared/components/, to use and change as your own. | | [`raea part`](part.md) | The old name of raea component: copy a ready-made component into the project's components/, to use and change as your own. | | [`raea add`](add.md) | Add, remove and install npm packages for a project, with no Node or npm: raea.lock and node_modules. | diff --git a/docs/manual/reference/cli/indexer.md b/docs/manual/reference/cli/indexer.md index c141ad815..e995d0ce9 100644 --- a/docs/manual/reference/cli/indexer.md +++ b/docs/manual/reference/cli/indexer.md @@ -1,7 +1,7 @@ --- title: "raea index" summary: "Make every picture on a folder or a drive searchable by words, embedded on this Mac's Neural Engine, and keep the index open for the raea app." -order: 32 +order: 31 sources: ["engine/cli/src/cli.rs"] --- diff --git a/docs/manual/reference/cli/library.md b/docs/manual/reference/cli/library.md index 0ce934507..a369df53e 100644 --- a/docs/manual/reference/cli/library.md +++ b/docs/manual/reference/cli/library.md @@ -1,7 +1,7 @@ --- title: "raea library" summary: "Search and manage the person's media libraries in the raea app: folders and drives indexed on this machine, searched by meaning." -order: 31 +order: 30 sources: ["engine/cli/src/library.ts"] --- diff --git a/docs/manual/reference/cli/part.md b/docs/manual/reference/cli/part.md index 89096b0bb..d5a1acd1f 100644 --- a/docs/manual/reference/cli/part.md +++ b/docs/manual/reference/cli/part.md @@ -1,7 +1,7 @@ --- title: "raea part" summary: "The old name of raea component: copy a ready-made component into the project's components/, to use and change as your own." -order: 28 +order: 27 sources: ["engine/cli/src/index.ts", "engine/cli/src/registry.gen.ts"] --- diff --git a/docs/manual/reference/cli/spec.md b/docs/manual/reference/cli/spec.md index bfa039a63..eeb1f251e 100644 --- a/docs/manual/reference/cli/spec.md +++ b/docs/manual/reference/cli/spec.md @@ -1,12 +1,12 @@ --- title: "raea spec" -summary: "Print a spec file's default export as JSON, checked against its schema: briefs, scripts, taste, plans and controllers." -order: 26 +summary: "Print a spec file's default export as JSON, checked against its schema: briefs, scripts, taste and plans." +order: 25 sources: ["engine/cli/src/spec.rs"] --- -raea's specs are TypeScript files whose default export is data: `brief.ts`, `NAME.script.ts`, `taste.ts`, -`plan.ts` and `controllers/ID.ts`. `raea spec` evaluates one, checks it against its schema and prints it as JSON, +raea's specs are TypeScript files whose default export is data: `brief.ts`, `NAME.script.ts`, `taste.ts` and +`plan.ts`. `raea spec` evaluates one, checks it against its schema and prints it as JSON, so an agent can read a brief without running anything else, and a wrong field is caught before it matters. ```sh @@ -20,7 +20,7 @@ raea spec notes.ts --as taste ## Usage ```sh -raea spec FILE.ts [--as brief|script|taste|plan|controller] (a spec's default export as JSON, checked against its schema: brief.ts, script.ts, taste.ts, plan.ts, controllers/ID.ts) +raea spec FILE.ts [--as brief|script|taste|plan] (a spec's default export as JSON, checked against its schema: brief.ts, script.ts, taste.ts, plan.ts) ``` Headless: it needs nothing running and opens no window. Takes up to 1 argument besides its flags. @@ -29,6 +29,6 @@ Headless: it needs nothing running and opens no window. Takes up to 1 argument b | Flag | Takes | What it does | | --- | --- | --- | -| `--as` | `brief\|script\|taste\|plan\|controller` | Which schema to check it against. By default from the file's name (`brief`, `script`, `plan`, a `controllers/` folder), and `taste` otherwise. | +| `--as` | `brief\|script\|taste\|plan` | Which schema to check it against. By default from the file's name (`brief`, `script`, `plan`), and `taste` otherwise. | diff --git a/docs/manual/reference/cli/workspace.md b/docs/manual/reference/cli/workspace.md index 5d73677ba..74a6cd3ef 100644 --- a/docs/manual/reference/cli/workspace.md +++ b/docs/manual/reference/cli/workspace.md @@ -1,12 +1,12 @@ --- title: "raea workspace" -summary: "Make, adopt or show a workspace: the git repository that holds a studio's projects and controllers." +summary: "Make, adopt or show a workspace: the git repository that holds a studio's projects and house taste." order: 23 sources: ["apps/workspace/src/workspace.rs"] --- A workspace is a git repository, one per studio or client, under your raea root (`~/Documents/raea` unless -`git config raea.root` says otherwise). It holds projects, controllers and the house taste in `taste.ts`. Every +`git config raea.root` says otherwise). It holds projects and the house taste in `taste.ts`. Every change raea makes in it is a commit. ```sh @@ -23,7 +23,7 @@ holding a `brief.ts` as a project. `raea workspace init` inside a cloned workspa ## Usage ```sh -raea workspace init [NAME] [--layout LAYOUT] | raea workspace adopt DIR [--name NAME] | raea workspace [--json] (a workspace: a git repo of projects and controllers under raea.root, ~/Documents/raea unless git config says) +raea workspace init [NAME] [--layout LAYOUT] | raea workspace adopt DIR [--name NAME] | raea workspace [--json] (a workspace: a git repo of projects under raea.root, ~/Documents/raea unless git config says) ``` Headless: it needs nothing running and opens no window. Takes up to 2 arguments besides its flags. diff --git a/docs/manual/reference/sdk/brief.md b/docs/manual/reference/sdk/brief.md index c21cfa8b4..954d75f9c 100644 --- a/docs/manual/reference/sdk/brief.md +++ b/docs/manual/reference/sdk/brief.md @@ -1,13 +1,13 @@ --- title: "raea/brief" -summary: "The specs an agent writes as data: brief, script, taste, plan and controller, checked against raea's schemas." +summary: "The specs an agent writes as data: brief, script, taste and plan, checked against raea's schemas." order: 4 sources: ["sdk/raea/src/brief.ts", "core/brief/src"] --- A spec is a TypeScript module whose default export is data: what a project is for (`brief`), a storyboard -(`script`), the person's or the house's taste (`taste`), a frozen plan for a build (`plan`) and a workspace's settings -(`controller`). It renders nothing and imports nothing that renders. The types are generated from the Rust schemas +(`script`), the person's, the house's or a project's taste and rules (`taste`), and a frozen plan for a build (`plan`). +It renders nothing and imports nothing that renders. The types are generated from the Rust schemas raea reads them with, so what TypeScript accepts is what raea accepts; [`raea spec`](../cli/spec.md) prints one as checked JSON. @@ -30,10 +30,10 @@ See [Workspaces and projects](../../concepts/workspaces.md) for where each spec ```ts -import { brief, controller, fingerprint, plan } from "raea/brief" +import { brief, fingerprint, plan, script } from "raea/brief" ``` -`raea/brief` exports 6 functions, 32 types. Source: [sdk/raea/src/brief.ts](https://github.com/shinyobjectz/raea/blob/main/sdk/raea/src/brief.ts). +`raea/brief` exports 5 functions, 27 types. Source: [sdk/raea/src/brief.ts](https://github.com/shinyobjectz/raea/blob/main/sdk/raea/src/brief.ts). ## Functions @@ -45,16 +45,6 @@ A project's brief (brief.ts): what to make, for whom, the one thing to believe, function brief(b: Brief): Brief ``` -### `controller` - -A workspace's controller (controllers/.ts): settings in groups of typed fields that every agent works to. -A standing decision ("every ad is 9:16"), not one piece of work: that's a feed item, and a note on it. The raea app -shows a new controller in the project's feed, and an agent brings one to the person with `controller_post`. - -```ts -function controller(c: ControllerInput): ControllerInput -``` - ### `fingerprint` A fingerprint (fingerprint.ts): its axes and the encoders its heads were trained on. @@ -81,7 +71,10 @@ function script(s: Script): Script ### `taste` -Taste (taste.ts): standing rules, some with a check `raea check --taste` holds every export to. +Taste (taste.ts): standing rules, the person's, a workspace's or a project's. A rule raea can hold the work to +carries a check: one of six measured forms (`{ form: "text-above", value: 75 }`), one of raea's checks by name +(`"loudness"`), or the project's own by its path from this file (`"../checks/clear.ts"`), with its `values`. +`raea check` runs every one that applies. ```ts function taste(t: Taste): Taste @@ -141,20 +134,6 @@ type Check = { "form": "text-hold", "value": number } | { "form": "text-above", type Concept = { /** * what it is ("flight feather", "toy rocking horse") */ what: string, style: string, /** * its largest extent, in metres */ size: number, /** * how close it's seen, in metres: sets how much detail up close must hold */ seenFrom: number, material?: string, use?: string, } ``` -### `Controller` - -```ts -type Controller = { id: string, title: string, help?: string, groups: Array, } -``` - -### `ControllerInput` - -A controller as written: ids are filled in from titles and labels when left out. - -```ts -type ControllerInput = Omit & { id?: string; groups: (Omit & { id?: string; fields: FieldInput[] })[]; } -``` - ### `Count` ```ts @@ -167,20 +146,6 @@ type Count = number | { min: number, max: number, } type Deliverable = { name: string, /** * "90 s", "16:9", "with sound" */ specs?: Array, /** * the feed item it lands as */ item?: string, /** * its own brief module, when it differs from the project in mode, look or audience */ brief?: string, /** * its script module (storyboard or screenplay) */ script?: s… ``` -### `Field` - -```ts -type Field = { id: string, label: string, help?: string, } & ({ "type": "toggle", value: boolean, } | { "type": "choice", options: Array, value: string, } | { "type": "number", value: number, unit?: string, min?: number, max?: number, step?: number, } | { "type": "text", value: string, placeholder?: s… -``` - -### `FieldInput` - -A field as written: its id is filled in from its label when left out. - -```ts -type FieldInput = Field extends infer F ? (F extends Field ? Omit & { id?: string } : never) : never -``` - ### `Fingerprint` | Field | Type | What it is | @@ -193,18 +158,6 @@ type FieldInput = Field extends infer F ? (F extends Field ? Omit & { i | `axes` (required) | `Axis[]` | What it notices, each axis with its words and the sense its head reads. | | `encoders` | `Record` | Each encoder's id and its file's sha256: heads trained on other encoders' columns are refused. | -### `Group` - -```ts -type Group = { id: string, title: string, help?: string, fields: Array, } -``` - -### `Kind` - -```ts -type Kind = { "type": "toggle", value: boolean, } | { "type": "choice", options: Array, value: string, } | { "type": "number", value: number, unit?: string, min?: number, max?: number, step?: number, } | { "type": "text", value: string, placeholder?: string, multiline?: boolean, } | { "type": "list",… -``` - ### `Level` ```ts @@ -252,7 +205,19 @@ type Reference = { target: string, note?: string, } ### `Rule` ```ts -type Rule = { text: string, check?: Check, } +type Rule = { text: string, check?: RuleCheck, /** * what a named or a .ts check is held to (`{ band: 0.8 }`); a form carries its own value */ values?: Record, /** * how bad what its check finds is: error, warn or note (unset: a form's findings are errors, another check's k… +``` + +### `RuleCheck` + +```ts +type RuleCheck = Check | string +``` + +### `RuleLevel` + +```ts +type RuleLevel = "error" | "warn" | "note" ``` ### `Scene` @@ -279,12 +244,6 @@ type Section = { heading: string, text: string, } type Stage = { name: string, tasks: Array, } ``` -### `Step` - -```ts -type Step = { name: string, by?: string, back?: string, } -``` - ### `Task` ```ts diff --git a/docs/manual/reference/sdk/check.md b/docs/manual/reference/sdk/check.md index 935eeb35a..8e69fef62 100644 --- a/docs/manual/reference/sdk/check.md +++ b/docs/manual/reference/sdk/check.md @@ -1,6 +1,6 @@ --- title: "raea/check" -summary: "A check written as a system over a composition's world: what `raea check` runs for a rule a controller holds." +summary: "A check written as a system over a composition's world: what `raea check` runs for a taste line's rule." order: 102 sources: ["sdk/raea/src/check.ts", "sdk/raea/src/facts.gen.ts", "apps/direction/src/check.rs"] --- @@ -8,15 +8,15 @@ sources: ["sdk/raea/src/check.ts", "sdk/raea/src/facts.gen.ts", "apps/direction/ A check holds the work to one line. It is a system over each frame's world, the same world [`raea world`](../cli/world.md) prints: a caption, a footage cut, a sound cue and a 3D part are entities with components, so one check reads the same for any of them. It finds entities, measures, and calls `found` for each -thing that breaks its line; it never prints. A rule in a project's controller names it by its path, with its values, +thing that breaks its line; it never prints. A line in a project's taste.ts names it by its path, with its values, and [`raea check`](../cli/check.md) runs it on every composition, on the frames it says it ranges over. A check that reads what only a render has (`needs: "render"`) waits for one, and says so. raea's own checks are the same thing written in Rust, under the names `text-hold`, `text-above`, `text-below`, `text-margin`, `loudness`, `still-max`, `text-read` and `floor`. ```ts -// controllers/rules.ts holds the rule: -// { label: "Captions clear the button band", type: "rule", check: "../checks/caption.ts", values: { band: 0.8 } } +// taste.ts holds the rule: +// { text: "Captions clear the button band", check: "checks/caption.ts", values: { band: 0.8 } } // checks/caption.ts import { check, found, type Layer, type Text } from "raea/check"; @@ -442,7 +442,7 @@ type Text = { words: string, font?: string, /** * its letters' height in px of a ### `Values` -A rule's values for its check (a controller's `values`, an ask's). +A rule's values for its check (a taste line's `values`, an ask's). ```ts type Values = Record diff --git a/docs/manual/reference/sdk/editor.md b/docs/manual/reference/sdk/editor.md index 6e991fcdc..7c5738bf0 100644 --- a/docs/manual/reference/sdk/editor.md +++ b/docs/manual/reference/sdk/editor.md @@ -423,7 +423,7 @@ function readAdds(raw: unknown): { adds: Adds; errors: string[]; } ### `readTimeline` -A timeline as an agent wrote it on a feed item or a controller's field (its own data: a schedule, a set list, a +A timeline as an agent wrote it on a feed item (its own data: a schedule, a set list, a shot plan), checked and made whole: what is well formed, and why the rest isn't. Frames are rounded to whole ones; a track with no kind is an overlay; ids must be there and not repeat. diff --git a/docs/manual/reference/sdk/index.md b/docs/manual/reference/sdk/index.md index 41a086b8d..71488223e 100644 --- a/docs/manual/reference/sdk/index.md +++ b/docs/manual/reference/sdk/index.md @@ -21,7 +21,7 @@ mirrors a Bevy type and has no comment of its own, the page shows Bevy's doc for - The sub-paths follow Bevy's crates: `raea/camera`, `raea/light`, `raea/pbr`, `raea/mesh`, `raea/transform`, `raea/post_process`, `raea/sprite`, `raea/ui` and the rest, so a Bevy example's imports map onto them. - `raea/3d` holds raea's scene layer: models, physics, splats, matchmoves and custom shader passes. -- `raea/brief` holds the specs: `brief`, `script`, `taste`, `plan` and `controller`. +- `raea/brief` holds the specs: `brief`, `script`, `taste` and `plan`. @@ -33,7 +33,7 @@ The composition, the app, and the specs and notes an agent writes. | --- | --- | --- | | [`raea`](raea.md) | The main entry: compositions, sequences, time, interpolation, springs, footage, sound and words. | 20 components, 9 hooks, 62 functions, 11 values, 107 types | | [`raea/app`](app.md) | The App, its plugins and schedules, and the registry a video's compositions are kept in. | 1 component, 1 hook, 4 functions, 3 classes, 17 values, 17 types | -| [`raea/brief`](brief.md) | The specs an agent writes as data: brief, script, taste, plan and controller, checked against raea's schemas. | 6 functions, 32 types | +| [`raea/brief`](brief.md) | The specs an agent writes as data: brief, script, taste and plan, checked against raea's schemas. | 5 functions, 27 types | | [`raea/note`](note.md) | A person's note as a file in the project: their words kept as written, and the asks the agent restates it as. | 1 function, 4 types | ## Time and motion @@ -95,7 +95,7 @@ Checks, lints and a headless App you can drive. | Import | What it's for | Exports | | --- | --- | --- | -| [`raea/check`](check.md) | A check written as a system over a composition's world: what `raea check` runs for a rule a controller holds. | 8 functions, 1 class, 38 types | +| [`raea/check`](check.md) | A check written as a system over a composition's world: what `raea check` runs for a taste line's rule. | 8 functions, 1 class, 38 types | | [`raea/fingerprint`](fingerprint.md) | A fingerprint (fingerprint.ts, docs/fingerprint.md): a person's or a team's sense of good work as axes, each with a small head over on-device encoders that `raea fingerprint` trains from their labels. `raea fingerprint new NAME` writes one with raea's base taxonomy; add an axis, reword one, or remove one, and raea retrains. Rust reads the default export (systems/fingerprint/src/taxonomy.rs), so these types follow its fields. | 1 function, 4 types | | [`raea/dev_tools`](dev_tools.md) | Checks and lints you can run from code: a motion performance's lint report. | 2 functions, 3 types | | [`raea/remote`](remote.md) | A headless Bevy App you open, step and query from TypeScript, through Bevy's remote protocol. | 1 class, 1 type | diff --git a/docs/manual/start/agents.md b/docs/manual/start/agents.md index 7b8665124..1a4897d29 100644 --- a/docs/manual/start/agents.md +++ b/docs/manual/start/agents.md @@ -41,9 +41,9 @@ In a project folder, print everything to read first, in order: raea context . ``` -That prints the person's taste (`~/.raea/taste/taste.ts`), the workspace's taste, the project's brief, its look, the -workspace's controllers (its settings and workflows), the craft floor, and the guide for each of the brief's modes. -Read all of it. A line in the person's taste beats any guide's default. +That prints the person's taste (`~/.raea/taste/taste.ts`), the workspace's taste, the project's own taste, its brief, +its look, the craft floor, and the guide for each of the brief's modes. Read all of it. A line in the person's taste +beats any guide's default. With no request in hand, `raea next` lists the two or three useful next steps for the project. Offer them to the person; don't run one unasked. @@ -123,7 +123,7 @@ text. - Final exports of motion graphics and type: `--quality master`. - Name files with lowercase letters, digits and hyphens only: `spring-launch-9x16.mp4`. -- Deliver to the workspace's controllers when they set sizes, platforms or loudness (`raea controller ls`). +- Deliver to the taste when it sets sizes, platforms or loudness (`raea context .` prints it). ## What an agent should never do diff --git a/docs/manual/tutorials/connect-your-agent.md b/docs/manual/tutorials/connect-your-agent.md index beb7e5cee..cf4e1d0a1 100644 --- a/docs/manual/tutorials/connect-your-agent.md +++ b/docs/manual/tutorials/connect-your-agent.md @@ -32,7 +32,7 @@ files directly. ## The primary Now open Settings, then Agents. The first row is the primary: the AI that runs your workspace. It answers in New chat -when no project is picked, takes what you write in the Inbox and on the Controllers page, and starts any work you don't +when no project is picked, takes what you write in the Inbox, and starts any work you don't hand to someone else. Pick any AI you've connected and one of its models, Kimi until you change it. That's all the primary is. raea doesn't add a director or a cast of agents on top. diff --git a/docs/manual/tutorials/controllers.md b/docs/manual/tutorials/controllers.md deleted file mode 100644 index f1644b228..000000000 --- a/docs/manual/tutorials/controllers.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: "Controllers" -summary: "A project's settings, which every agent reads before it works: change a value in place, describe a new controller in plain words, and see how agents post a decision to the feed." -order: 6 -sources: ["apps/app/src/controllers", "apps/workspace/src/controllers.rs", "sdk/raea/src/brief.ts", "docs/projects.feature"] -tutorial: "controllers" ---- - -Controllers are how you tell every agent in a project how things should be done, once. This tutorial reads a -project's controllers, changes a value, and adds a new controller by describing it. - -## What a controller is - -A controller is a page of settings for a project, such as its delivery format, its brand, or how review works. Every -agent working in the project reads the controllers before it starts. So when you change a value, the next piece of work -follows it. - -## The Controllers page - -Open a project's folder and choose Controllers. Each controller is a card, with its fields in groups. A field can be a -toggle, a choice, a number, some text, a list, a set of agents, or a whole workflow. Change a value in place, and it's -saved at once, for the whole project. - -## Make one in plain words - -To add a controller, press New controller, and say what you want in plain words. Your workspace's primary builds it -from raea's field types, and it appears on the page, ready to adjust. - -## Workflows - -A workflow field lays out the steps a piece of work goes through, and who does each one: an agent, or you. When a step -fails, the workflow says which step the work goes back to. - -## When an agent needs a decision - -When an agent needs a decision that should hold for every piece from now on, it puts the controller in the feed, with -one line on what it needs. Set the value right there in the card, and every agent works to it. - -## Controllers are files - -Each controller is a TypeScript file in the workspace's controllers folder, and every change is a commit, by you or by -the agent that made it. So any agent, even one in a terminal, can read and change them with raea controller. - -```sh -raea controller ls -raea controller set delivery.format.aspect-ratio 9:16 --by agent -raea controller write controllers/review.ts -``` - -Next: [Publish](publish.md). diff --git a/docs/manual/tutorials/extend.md b/docs/manual/tutorials/extend.md index ec1e63b35..19a727fe2 100644 --- a/docs/manual/tutorials/extend.md +++ b/docs/manual/tutorials/extend.md @@ -1,13 +1,13 @@ --- title: "Extend raea with the SDK" -summary: "Compositions and controllers are TypeScript on raea's SDK: write one, render it, post it to the feed with the feed's tools, or ask your agent to make new feed items and controllers for you." +summary: "Compositions and the rules they keep are TypeScript on raea's SDK: write one, render it, post it to the feed with the feed's tools, or ask your agent to make new feed items and rules for you." order: 8 -sources: ["sdk/raea/src", "sdk/raea/src/brief.ts", "apps/app/src/acp/protocol.ts", "docs/manual/examples/title.tsx", "apps/workspace/src/controllers.rs"] +sources: ["sdk/raea/src", "sdk/raea/src/brief.ts", "apps/app/src/acp/protocol.ts", "docs/manual/examples/title.tsx", "apps/direction/src/check.rs"] tutorial: "extend" --- Everything raea makes and every setting it keeps is TypeScript you can read and write. This tutorial writes a small -composition, renders it, posts it to the feed, writes a controller, and then hands the same jobs to an agent. +composition, renders it, posts it to the feed, writes a rule it must keep, and then hands the same jobs to an agent. ## The SDK @@ -27,16 +27,16 @@ The agents raea starts get the feed's own tools. Feed post puts a render, a stil feed. It takes a title and the file, and to post a new version, it names the item it replaces, with one line on what changed. Feed propose suggests something to make next, for you to accept first. -## A controller from code +## A rule from code -A controller is a TypeScript file too. It exports controller, from raea slash brief, with groups of typed fields. Write -one, then run raea controller write, and it's on the Controllers page for every agent to read. Agents in the app use -the controller write tool, and the page shows the new controller as soon as they do. +The rules every piece keeps are a TypeScript file too: the project's taste. It exports taste, from raea slash brief, +with lines in plain words, and a line raea can measure carries the check that holds it. Run raea check, and every +composition is held to every line. Agents in the app add a line with the rule add tool. ## Ask your agent instead So you rarely write any of this yourself. Ask your agent in plain words, in New chat. It writes the composition, checks -it, renders it, and posts it to the feed. Ask for a controller, and it builds one and puts it on the page. You review +it, renders it, and posts it to the feed. Tell it a rule, and it adds the line and checks the work against it. You review what lands, and leave notes, as you would on anything else. ## Extend the engine @@ -54,21 +54,21 @@ registerRoot(() => R { // an agent's report of a bug in raea itself, to raea's server (engine/cli/src/bug.ts; Shane 11-16) let usage = format!("{usage}\n raea bug TITLE... --text TEXT [--command CMD] [--error TEXT] [--agent NAME] [--dry-run] (a bug in raea itself, not in your own composition, sent to raea's server with raea's version and the OS, no account needed: words only, paths, emails and keys taken out before it goes; five a day from a machine, the same bug again counted on the first report; --dry-run prints what would go and sends nothing)"); // a workspace's files and specs (docs/projects.feature), listed under render's usage like library - let usage = format!("{usage}\n raea spec FILE.ts [--as brief|script|taste|plan|controller] (a spec's default export as JSON, checked against its schema: brief.ts, script.ts, taste.ts, plan.ts, controllers/ID.ts)\n raea workspace init [NAME] [--layout LAYOUT] | raea workspace adopt DIR [--name NAME] | raea workspace [--json] (a workspace: a git repo of projects and controllers under raea.root, ~/Documents/raea unless git config says)\n raea project new NAME [--storage inline|submodule] | raea project split NAME [--remote URL] | raea project join NAME | raea project [--json] (a project in the workspace: its folder, brief.ts, media/, out/; split and join keep its history)\n raea controller ls [--json] | raea controller get PATH [--json] | raea controller set PATH VALUE [--project] [--by NAME] | raea controller write FILE.ts [--by NAME] | raea controller rm ID [--by NAME] (the workspace's controllers, controllers/ID.ts; PATH is controller.group.field; every change a commit)\n raea check EDIT.tsx --quick [--shape S] [--platform P] [--taste T] [-o check.json] (three stills of a composition checked for text: clipped, cramped, safe areas, sizes; about a second)\n raea hook [claude|codex|gemini|kimi] (every agent's tool hooks, which raea skills install adds: before a shell command, media opened in the Mac's viewer while the raea app is installed is stopped once for raea show (the same command again goes through); after a save, the quick check on a composition)\n raea next [DIR] (the two or three useful next steps for the project, from its brief, compositions, renders and checks)\n raea doctor [--fix] [DIR] (what doesn't match this raea: old brief files, an older workspace format, an agent's skill from another version)\n raea app run|check|bundle APP.tsx [--target web|native] [--size WxH] [--script steps.json] [--png DIR] [-o App.app] (a TSX app on @raea/ui: its window, the headless check, a Mac app; web is Blitz on Bevy, native is Rune; the app's `export const app` sets the target, web when it doesn't; raea rune ... is --target native)\n {}\n {}\n {} ({})\n {}\n {}\n {}", skill::USAGE, tools::blender::USAGE, tools::motion::SETUP_USAGE, tools::motion::SETUP_ABOUT, raea_app_engines::godot::USAGE, raea_app_engines::shot::USAGE, raea_app_engines::round::USAGE); + let usage = format!("{usage}\n raea spec FILE.ts [--as brief|script|taste|plan] (a spec's default export as JSON, checked against its schema: brief.ts, script.ts, taste.ts, plan.ts)\n raea workspace init [NAME] [--layout LAYOUT] | raea workspace adopt DIR [--name NAME] | raea workspace [--json] (a workspace: a git repo of projects under raea.root, ~/Documents/raea unless git config says)\n raea project new NAME [--storage inline|submodule] | raea project split NAME [--remote URL] | raea project join NAME | raea project [--json] (a project in the workspace: its folder, brief.ts, media/, out/; split and join keep its history)\n raea check EDIT.tsx --quick [--shape S] [--platform P] [--taste T] [-o check.json] (three stills of a composition checked for text: clipped, cramped, safe areas, sizes; about a second)\n raea hook [claude|codex|gemini|kimi] (every agent's tool hooks, which raea skills install adds: before a shell command, media opened in the Mac's viewer while the raea app is installed is stopped once for raea show (the same command again goes through); after a save, the quick check on a composition)\n raea next [DIR] (the two or three useful next steps for the project, from its brief, compositions, renders and checks)\n raea doctor [--fix] [DIR] (what doesn't match this raea: old brief files, an older workspace format, an agent's skill from another version)\n raea app run|check|bundle APP.tsx [--target web|native] [--size WxH] [--script steps.json] [--png DIR] [-o App.app] (a TSX app on @raea/ui: its window, the headless check, a Mac app; web is Blitz on Bevy, native is Rune; the app's `export const app` sets the target, web when it doesn't; raea rune ... is --target native)\n {}\n {}\n {} ({})\n {}\n {}\n {}", skill::USAGE, tools::blender::USAGE, tools::motion::SETUP_USAGE, tools::motion::SETUP_ABOUT, raea_app_engines::godot::USAGE, raea_app_engines::shot::USAGE, raea_app_engines::round::USAGE); let (export_game, capcut, layers, xml, scene, physics, splat, wear) = (raea_app_game::USAGE, raea_app_capcut::USAGE, raea_app_layers::USAGE, raea_app_layers::USAGE_XML, export::SCENE_USAGE, motion::physics::USAGE, tools::splat::USAGE, raea_runtime_wear::USAGE); let apps = format!(" {}\n {}\n {}\n {}\n {}\n {}\n {}\n {}\n {}\n", raea_app_direction::check::USAGE, raea_app_check::USAGE, raea_app_solid::USAGE, raea_app_judge::USAGE, raea_app_direction::USAGE, raea_app_direction::findings::USAGE, raea_app_notes::USAGE, raea_app_fingerprint::USAGE, raea_sys_index::cli::USAGE); return Ok(format!("raea: renders, plays and checks raea compositions (React and TypeScript) on the GPU.\n\nusage: {usage}\n raea init (a project's files where they're missing: edit.tsx, cuts.ts, components/, AGENTS.md)\n raea cut TAKE \"line\" ... | --at A-B ... [--append] (cuts.ts and words.json: a take under media/ cut in the pauses around each line it says, transcribed first if it has no TAKE.words.json; or at those seconds)\n raea frame TAKE [--at S] (how a take fits the edit: a talking take for , a screen for , from where its face is)\n raea component list | raea component add NAME ... [--shared] [--force] | raea part list | raea part add NAME ... [--shared] [--force] (a ready component or set copied into components/, or the workspace's shared/components/ with --shared, yours to change; raea part is its old name)\n raea brand DOMAIN|URL (the brand kit read from its website on this machine: brand/brand.css, brand/brand.json, BRAND.md, logos in media/brand; says when a plain fetch saw too little)\n raea guide [NAME] (craft, the floor read before any edit; the modes: pitch, explain, story, play, tool; motion, music, layout and the rest; bevy and bevy/NAME for 3D)\n raea context PROJECT (what to read before working on a project: taste, brief, look, the floor and its modes' guides)\n{apps} raea play EDIT.tsx [--input | --input-script KEYS.json] [--size WxH] [--seconds N|end] (a game, live; also: --input-log FILE --offscreen --snapshot T FILE --json FILE --seek F FILE --pick X,Y --view YAW,PITCH,DISTANCE --scrub N --baked --autoplay --no-vsync --master --3d)\n {export_game} (a game as a program of its own: a Mac app or a command)\n {capcut}\n {layers}\n {xml}\n {scene} (what each 3D part rests on: floating, sunk and clipping parts; light: the scene's lighting)\n {physics} (the bakes and make)\n {wear} (a .glb's weathering causes for raea/wear: the model with a second UV set and its cause maps, made once in the asset store)\n {splat} (footage trained into a Gaussian splat for ; setup installs its tools)\n raea run SCRIPT.ts (a TypeScript program on the engine, headless: its default export is called, what it prints is the answer; a check like a room's checkLayout; also: --timeout S)\n raea gen image|video|music|sfx|speech|mesh|text \"PROMPT\" | gen plan|run FLOW.ts|FLOW.json | gen comfy import|export|run|schema FILE | gen models | gen balance (generated media through made.app, fal, Replicate, OpenRouter, Modal or ComfyUI; ComfyUI workflows both ways: raea gen alone lists its flags)\n {neural_usage} (DLSS 5 neural rendering on a `render --aov` folder, with its motion and depth: your own MLX-DLSS build and weights, RAEA_MLXDLSS and RAEA_DLSS_MODEL)\n {light_usage} (each scene on each light path against its path-traced reference: distance in stops, the worst tile, a moving shot's flicker, a frame's cost; DIR/report.json)\n raea mezz [--check] PATH... (an intra-only ProRes copy of each long-GOP source over 1080p, for smooth scrubbing; --check says which would get one)\n raea traces [show [N|last|DIR]] (the sessions raea left, newest first: how each ended, its glitches; show tells one in full)")); @@ -174,9 +174,9 @@ pub fn run(args: &[String]) -> R { if args[0] == "project" { return raea_app_workspace::project(&args[1..]); } - // `controller …`: the workspace's controllers/.ts and a project's overrides (PJ2) + // controllers are gone (11-20): an agent with an older skill is told where their parts went if args[0] == "controller" { - return raea_app_workspace::controller(&args[1..], spec::spec_json); + return Err("raea controller is gone: a standing rule or preference is a line in taste.ts (with a check when raea can measure it), a decision for now is a feed post with an ask, and a piece's settings live in its composition".into()); } // `skill [NAME]` and `skills install --agent A`: the skills this raea ships, for its version (SK6) if args[0] == "skill" { diff --git a/engine/cli/src/guide.rs b/engine/cli/src/guide.rs index ea5aa7630..dcf029c54 100644 --- a/engine/cli/src/guide.rs +++ b/engine/cli/src/guide.rs @@ -130,9 +130,14 @@ fn context_body(out: &mut String, dir: &Path, taste_dir: Option, modes: if let Some((p, text)) = raea_app_workspace::up(&dir, ".raea/workspace").and_then(|ws| spec::taste_file(&ws, "taste")) { section(format!("WORKSPACE TASTE {}", p.display()), text); } - // the workspace's controllers with this project's overrides (its settings and workflows, which the work follows), and - // the project's compositions, components and controllers as raea reads them (docs/projects.feature PJ8) - for (name, text) in raea_app_workspace::context(dir, spec::spec_json) { + // the project's own rules, which raea check holds beside the person's and the workspace's (DR4) + if raea_app_workspace::up(dir, ".raea/workspace").as_deref() != Some(dir) + && let Some((p, text)) = spec::taste_file(dir, "taste") + { + section(format!("PROJECT TASTE {}", p.display()), text); + } + // the project's compositions and components as raea reads them (docs/projects.feature PJ8) + for (name, text) in raea_app_workspace::context(dir) { section(name, text); } section(format!("BRIEF {}", brief_path.display()), brief.clone()); diff --git a/engine/cli/src/spec.rs b/engine/cli/src/spec.rs index 5c89558a6..40255d73f 100644 --- a/engine/cli/src/spec.rs +++ b/engine/cli/src/spec.rs @@ -1,5 +1,5 @@ //! Specs written in TypeScript (docs/handoff/authoring.md, docs/projects.feature PJ0): brief.ts, script.ts, taste.ts -//! and a workspace's controllers. A spec is a module whose default export is data; the engine evaluates it headless +//! and plan.ts. A spec is a module whose default export is data; the engine evaluates it headless //! (bundle_module with PRINT_DEFAULT, run_bundle) and Rust reads the JSON against the schema in core/brief, so tsc's errors come first and //! these come second, naming the field. use super::*; @@ -89,15 +89,14 @@ pub fn tastes_ts(args: &[String]) -> R> { } /// `raea spec FILE.ts [--as KIND]`: the default export as JSON, checked as KIND (by default from the file's name: -/// brief, script, taste or plan in it, controller under controllers/; anything else is checked as Taste, the files in +/// brief, script, taste or plan in it; anything else is checked as Taste, the files in /// ~/.raea/taste being named for their kind). pub fn spec_cli(args: &[String]) -> R { - const USAGE: &str = "usage: raea spec FILE.ts [--as brief|script|taste|plan|controller]"; + const USAGE: &str = "usage: raea spec FILE.ts [--as brief|script|taste|plan]"; let file = args.iter().enumerate().find(|(i, a)| !a.starts_with("--") && (*i == 0 || args[i - 1] != "--as")).map(|(_, a)| PathBuf::from(a)).ok_or(USAGE)?; - let named = file.to_string_lossy().to_lowercase(); let kind = args.iter().position(|a| a == "--as").and_then(|i| args.get(i + 1)).cloned().unwrap_or_else(|| { let base = file.file_name().map(|n| n.to_string_lossy().to_lowercase()).unwrap_or_default(); - ["brief", "script", "plan"].iter().find(|k| base.contains(*k)).map(|k| k.to_string()).unwrap_or(if named.contains("controllers/") { "controller".into() } else { "taste".into() }) + ["brief", "script", "plan"].iter().find(|k| base.contains(*k)).map(|k| k.to_string()).unwrap_or_else(|| "taste".into()) }); let json = spec_json(&file)?; let name = file.file_name().map(|n| n.to_string_lossy().into_owned()).unwrap_or_default(); @@ -106,11 +105,7 @@ pub fn spec_cli(args: &[String]) -> R { "script" => serde_json::to_value(schema::read::(&name, &json)?), "taste" => serde_json::to_value(schema::read::(&name, &json)?), "plan" => serde_json::to_value(schema::read::(&name, &json)?), - "controller" => { - let raw: serde_json::Value = serde_json::from_str(&json).map_err(|e| format!("{name}: {e}"))?; - serde_json::to_value(schema::controller::normalize(&raw).map_err(|e| format!("{name}: {e}"))?) - } - k => return Err(format!("raea spec can't check a {k:?}: brief, script, taste, plan or controller\n{USAGE}")), + k => return Err(format!("raea spec can't check a {k:?}: brief, script, taste or plan\n{USAGE}")), } .map_err(|e| e.to_string())?; Ok(value.to_string()) diff --git a/engine/cli/src/tests.rs b/engine/cli/src/tests.rs index 48cf1de5a..90c802572 100644 --- a/engine/cli/src/tests.rs +++ b/engine/cli/src/tests.rs @@ -45,9 +45,8 @@ fn help_json_is_every_listed_verb() { let verbs: Vec<&str> = j["verbs"].as_array().unwrap().iter().map(|v| v["verb"].as_str().unwrap()).collect(); assert_eq!(verbs, verb_list(&help).iter().map(String::as_str).collect::>()); assert!(!verbs.contains(&"compositions"), "the help's opening line isn't a verb: {verbs:?}"); - let controller = j["verbs"].as_array().unwrap().iter().find(|v| v["verb"] == "controller").unwrap(); - assert_eq!(controller["args"], 3); - assert!(controller["flags"].as_array().unwrap().iter().any(|f| f["flag"] == "--by" && f["values"] == 1)); + let project = j["verbs"].as_array().unwrap().iter().find(|v| v["verb"] == "project").unwrap(); + assert!(project["flags"].as_array().unwrap().iter().any(|f| f["flag"] == "--storage" && f["values"] == 1)); assert!(j["verbs"].as_array().unwrap().iter().any(|v| v["verb"] == "gen" && v["own_parser"] == true)); } diff --git a/sdk/guides/craft/ROUTER.md b/sdk/guides/craft/ROUTER.md index 93e724e4b..54244a2bb 100644 --- a/sdk/guides/craft/ROUTER.md +++ b/sdk/guides/craft/ROUTER.md @@ -57,9 +57,9 @@ leads. raea will add modes as its work grows; `raea context` says when a brief n 5. **The floor:** read it right before you edit. 6. **Make it.** 7. **Evidence:** run `raea check`, look at the frames, critique against the mode's guide, fix, and look again. - A line the work must keep every round is a rule, not a reminder: a field `{ label, type: "rule", check, values }` - in the project's controller, whose check is one of raea's by name (`text-above`, `loudness`) or a `.ts` check you - write with `raea/check` (`check({ id, text }, (world, frame, values) => ...)` and `found(...)`). `raea check + A line the work must keep every round is a rule, not a reminder: a line `{ text, check, values }` in the project's + taste.ts, whose check is one of raea's by name (`text-above`, `loudness`) or a `.ts` check you write with + `raea/check` (`check({ id, text }, (world, frame, values) => ...)` and `found(...)`). `raea check PROJECT` runs every rule on every composition and says what waits for a render. A quick edit (one value, one word, one cut) skips to the floor and makes the change. "This isn't working" means a diff --git a/sdk/guides/craft/bevy/blender.md b/sdk/guides/craft/bevy/blender.md index 281481f87..e7b6498b8 100644 --- a/sdk/guides/craft/bevy/blender.md +++ b/sdk/guides/craft/bevy/blender.md @@ -202,8 +202,7 @@ import { BlenderShot } from "raea/blender/shot"; server's env. It can otherwise send prompts, code and screenshots to its author. - `generate_3d` can cost the person a credit, and makes one object only; `raea gen` is the generation route. Ask first. -In the raea app, a workspace gives it to the feed's agents with a controller's servers field holding -`uvx mcp-for-blender` (`raea controller set PATH VALUE`). +`raea skills install --agent NAME` adds it to that agent as an MCP server (`--no-mcp` leaves it out). ## Licences diff --git a/sdk/guides/craft/match-cuts/thirds.ts b/sdk/guides/craft/match-cuts/thirds.ts index e84f8ee55..a9328d3bd 100644 --- a/sdk/guides/craft/match-cuts/thirds.ts +++ b/sdk/guides/craft/match-cuts/thirds.ts @@ -1,6 +1,6 @@ // The match cuts, checked in the render (`raea guide match-cuts`): at every cut of a chain (chain.ts), the hooked part // sits at its thirds place on the frame before the cut and on the frame after it. A project makes the check from its -// chain in a file of its own, and a rule (a controller's, or a note's ask) names that file: +// chain in a file of its own, and a rule (a taste line, or a note's ask) names that file: // // // checks/film-cuts.ts // import { landsOnThirds } from "./match-cuts/thirds"; diff --git a/sdk/guides/craft/motion/delivery.md b/sdk/guides/craft/motion/delivery.md index 3b935bf8e..aef7bf5a5 100644 --- a/sdk/guides/craft/motion/delivery.md +++ b/sdk/guides/craft/motion/delivery.md @@ -2,10 +2,10 @@ ## What to do -- Start from what's asked for. The brief's deliverables say the pieces; the workspace's delivery controller, when - there is one (`raea controller ls`, or `controllers_read` in the app), says the shapes, lengths, platforms, caption - rule and loudness for every piece. Work to it. When neither says where a piece goes, ask once with your best guess, - or write the guess and add it to the brief's `assumed`. +- Start from what's asked for. The brief's deliverables say the pieces; the taste (`raea context .`, or `rules_read` + in the app: the person's, the workspace's and the project's taste.ts) says the shapes, lengths, platforms, caption + rule and loudness every piece keeps. Work to it. When neither says where a piece goes, ask once with your best + guess, or write the guess and add it to the brief's `assumed`. - Make each shape as its own composition from the same scenes (`motion/compositions`), laid out for that shape: a vertical cut puts its type and faces where a vertical frame has room, it doesn't crop the wide one. Name them by shape (`launch-9x16`, `launch-1x1`, `launch-16x9`). @@ -16,7 +16,7 @@ - Keep text and faces out of the platform's UI zones for that shape (reference/platforms.md; `motion/placement` for how), then check the export against the platform: `raea check out/launch-9x16.mp4 --manifest out/render.json --shape 9:16 --platform tiktok`. -- Captions: burn them in for feeds that play without sound, unless the delivery controller says captions off; then +- Captions: burn them in for feeds that play without sound, unless the taste says captions off; then burn none, and leave the words file beside the export for the platform's own captions. - Sound to -14 LUFS integrated with true peak at or below -1 dBTP: one `` per composition does it (`motion/sound`). A spec that names another number wins. @@ -71,7 +71,7 @@ exports and renders), so one file can't be right in both. vertical out as its own composition. - Text in the bottom quarter of a vertical frame, where every short-video network puts its caption and buttons. - A 15 s cutdown that is the first 15 seconds of the long cut, with no ending. -- Captions burned in on a piece whose delivery controller says captions off, or burned in twice: once by the piece, +- Captions burned in on a piece whose taste says captions off, or burned in twice: once by the piece, once by the platform's auto-captions the person turned on. - `final-v2-FINAL.mp4`, `Launch Video (1).mp4`, or a new render written over the version the person last saw. - Tags that change keys between items (`tiktok`, `platform:TikTok`, `network:tiktok`): the Table makes three columns. diff --git a/sdk/guides/craft/motion/match-cuts.md b/sdk/guides/craft/motion/match-cuts.md index 04bfdcab3..a00dcea1d 100644 --- a/sdk/guides/craft/motion/match-cuts.md +++ b/sdk/guides/craft/motion/match-cuts.md @@ -143,11 +143,11 @@ import { landsOnThirds } from "./match-cuts/thirds"; import film from "../film.chain"; export default landsOnThirds(film); -// controllers/rules.ts: the project's controller, holding the rule; its check is a path from this file (a note's ask -// names the same file in its `check`) -import { controller } from "raea/brief"; -export default controller({ title: "Rules", groups: [{ title: "The cuts", fields: [ - { label: "the cuts land on the thirds", type: "rule", check: "../checks/film-cuts.ts", values: { tolerance: 0.06 } }, +// taste.ts: the project's taste, holding the rule; its check is a path from this file (a note's ask names the same +// file in its `check`) +import { taste } from "raea/brief"; +export default taste({ title: "Rules", sections: [{ heading: "The cuts", rules: [ + { text: "the cuts land on the thirds", check: "checks/film-cuts.ts", values: { tolerance: 0.06 } }, ] }] }); ``` diff --git a/sdk/guides/craft/verbs/adapt.md b/sdk/guides/craft/verbs/adapt.md index 0b1664fe6..0f11cf74d 100644 --- a/sdk/guides/craft/verbs/adapt.md +++ b/sdk/guides/craft/verbs/adapt.md @@ -4,7 +4,7 @@ Notes like these: "we need it in 16:9", "a square one for the feed", "4:5 for In YouTube". The same piece made right for another size, length or platform; never a crop of the old one. ## Assess -- The controllers' delivery specs name the sizes, lengths and platforms; work to those. +- The brief's deliverables and the taste name the sizes, lengths and platforms; work to those. - For each size, find what no longer fits: type that wraps, a face cut off, a part in a platform's button zone, a hold that's too long for a shorter cut. diff --git a/sdk/guides/craft/verbs/layout.md b/sdk/guides/craft/verbs/layout.md index d7fa4d950..802642ec8 100644 --- a/sdk/guides/craft/verbs/layout.md +++ b/sdk/guides/craft/verbs/layout.md @@ -18,7 +18,7 @@ space", "the logo's lost". Where things sit in the frame and how much room each - One focal point per moment. Make it bigger or give it more room; make the rest smaller rather than moving it away. - Put parts on a grid: shared left edges, shared baselines, the same margin on every side (`raea guide motion/layout`). - Use the room on purpose: space around the focal point, not spread evenly across the frame. -- Keep text and faces inside the safe zones of every platform the controllers name. +- Keep text and faces inside the safe zones of every platform the brief or the taste names. ## Verify - Stills at the same frames, before and after (`raea render --at`), at ship size. The eye goes to the right place first. diff --git a/sdk/raea/src/brief.gen.ts b/sdk/raea/src/brief.gen.ts index 8f4923918..08e977a93 100644 --- a/sdk/raea/src/brief.gen.ts +++ b/sdk/raea/src/brief.gen.ts @@ -144,7 +144,20 @@ export type TasteSection = { */ heading: string, rules: Array, }; -export type Rule = { text: string, check?: Check, }; +export type Rule = { text: string, check?: RuleCheck, +/** + * what a named or a .ts check is held to (`{ band: 0.8 }`); a form carries its own value + */ +values?: Record, +/** + * how bad what its check finds is: error, warn or note (unset: a form's findings are errors, another check's keep + * its own level) + */ +level?: RuleLevel, }; + +export type RuleCheck = Check | string; + +export type RuleLevel = "error" | "warn" | "note"; export type Check = { "form": "text-hold", "value": number } | { "form": "text-above", "value": number } | { "form": "text-below", "value": number } | { "form": "text-margin", "value": number } | { "form": "loudness", "value": number } | { "form": "still-max", "value": number }; @@ -189,13 +202,3 @@ material?: string, style?: string, * what a near crop of it must show */ near?: string, }; - -export type Controller = { id: string, title: string, help?: string, groups: Array, }; - -export type Group = { id: string, title: string, help?: string, fields: Array, }; - -export type Field = { id: string, label: string, help?: string, } & ({ "type": "toggle", value: boolean, } | { "type": "choice", options: Array, value: string, } | { "type": "number", value: number, unit?: string, min?: number, max?: number, step?: number, } | { "type": "text", value: string, placeholder?: string, multiline?: boolean, } | { "type": "list", value: Array, placeholder?: string, } | { "type": "agents", value: Array, } | { "type": "channels", value: Array, } | { "type": "workflow", value: Array, channels?: Array, } | { "type": "servers", value: Array, } | { "type": "skills", value: Array, } | { "type": "rule", check: string, values: Record, level?: string, }); - -export type Kind = { "type": "toggle", value: boolean, } | { "type": "choice", options: Array, value: string, } | { "type": "number", value: number, unit?: string, min?: number, max?: number, step?: number, } | { "type": "text", value: string, placeholder?: string, multiline?: boolean, } | { "type": "list", value: Array, placeholder?: string, } | { "type": "agents", value: Array, } | { "type": "channels", value: Array, } | { "type": "workflow", value: Array, channels?: Array, } | { "type": "servers", value: Array, } | { "type": "skills", value: Array, } | { "type": "rule", check: string, values: Record, level?: string, }; - -export type Step = { name: string, by?: string, back?: string, }; diff --git a/sdk/raea/src/brief.ts b/sdk/raea/src/brief.ts index c15d8d6ce..3819766c3 100644 --- a/sdk/raea/src/brief.ts +++ b/sdk/raea/src/brief.ts @@ -7,29 +7,20 @@ // // The types are generated from the Rust schemas (core/brief, raea-core-brief) into brief.gen.ts, so what tsc checks is // what raea reads: `raea context` evaluates the module and Rust validates its default export again. -import type { Brief, Controller, Field, Group, Plan, Script, Taste } from "./brief.gen"; +import type { Brief, Plan, Script, Taste } from "./brief.gen"; export type * from "./brief.gen"; export { fingerprint } from "./fingerprint"; export type { Applies, Axis, Fingerprint, Modality } from "./fingerprint"; -/** A field as written: its id is filled in from its label when left out. */ -export type FieldInput = Field extends infer F ? (F extends Field ? Omit & { id?: string } : never) : never; -/** A controller as written: ids are filled in from titles and labels when left out. */ -export type ControllerInput = Omit & { - id?: string; - groups: (Omit & { id?: string; fields: FieldInput[] })[]; -}; - /** A project's brief (brief.ts): what to make, for whom, the one thing to believe, its deliverables and staged tasks. */ export const brief = (b: Brief): Brief => b; /** A storyboard or a screenplay (script.ts): scenes, beats, lines, camera and cut. */ export const script = (s: Script): Script => s; -/** Taste (taste.ts): standing rules, some with a check `raea check --taste` holds every export to. */ +/** Taste (taste.ts): standing rules, the person's, a workspace's or a project's. A rule raea can hold the work to + * carries a check: one of six measured forms (`{ form: "text-above", value: 75 }`), one of raea's checks by name + * (`"loudness"`), or the project's own by its path from this file (`"../checks/clear.ts"`), with its `values`. + * `raea check` runs every one that applies. */ export const taste = (t: Taste): Taste => t; /** An object's plan (plan.ts): its parts by name, levels, counts, materials. */ export const plan = (p: Plan): Plan => p; -/** A workspace's controller (controllers/.ts): settings in groups of typed fields that every agent works to. - * A standing decision ("every ad is 9:16"), not one piece of work: that's a feed item, and a note on it. The raea app - * shows a new controller in the project's feed, and an agent brings one to the person with `controller_post`. */ -export const controller = (c: ControllerInput): ControllerInput => c; diff --git a/sdk/raea/src/check.ts b/sdk/raea/src/check.ts index 387e7d41b..8fb94f8d3 100644 --- a/sdk/raea/src/check.ts +++ b/sdk/raea/src/check.ts @@ -5,8 +5,8 @@ // the same thing written in Rust, run under the same names, and a check reads the same for a mesh, a caption, a cut // or a cue: nothing here is 3D's. // -// // checks/clear.ts, run by a rule a controller holds: -// // { label: "Captions clear the button band", type: "rule", check: "../checks/clear.ts", values: { band: 0.8 } } +// // checks/clear.ts, run by a line in the project's taste.ts: +// // { text: "Captions clear the button band", check: "checks/clear.ts", values: { band: 0.8 } } // import { check, found, type Text } from "raea/check"; // export default check({ id: "caption-clear", text: "Captions clear the button band" }, (world, frame, values) => { // for (const t of world.find({ with: ["Text", "Layer"] })) { @@ -38,7 +38,7 @@ export interface CheckMeta { frames?: Frames; } -/** A rule's values for its check (a controller's `values`, an ask's). */ +/** A rule's values for its check (a taste line's `values`, an ask's). */ export type Values = Record; /** What one rule's run of a check keeps from frame to frame: empty on its first frame, its own (two asks that run * one check each have theirs). */ diff --git a/sdk/timeline/src/read.ts b/sdk/timeline/src/read.ts index 4d0a05439..ed5032a58 100644 --- a/sdk/timeline/src/read.ts +++ b/sdk/timeline/src/read.ts @@ -448,7 +448,7 @@ export function seqEdits(t: Timeline, op: Op): SeqEdit[] | { why: string } { // ---------------------------------------------------------------- a timeline an item declares (TL0d) -/** A timeline as an agent wrote it on a feed item or a controller's field (its own data: a schedule, a set list, a +/** A timeline as an agent wrote it on a feed item (its own data: a schedule, a set list, a * shot plan), checked and made whole: what is well formed, and why the rest isn't. Frames are rounded to whole * ones; a track with no kind is an overlay; ids must be there and not repeat. */ export function readTimeline(raw: unknown): { timeline?: Timeline; errors: string[] } { diff --git a/sdk/timeline/test/read.test.ts b/sdk/timeline/test/read.test.ts index 7861fa0c6..29a866dfd 100644 --- a/sdk/timeline/test/read.test.ts +++ b/sdk/timeline/test/read.test.ts @@ -281,7 +281,7 @@ describe("TL14b: a sound in the feed is its tracks", () => { }) }) -describe("TL0d: a feed item or a controller declares a timeline of its own data", () => { +describe("TL0d: a feed item declares a timeline of its own data", () => { test("what is well formed is a timeline the editor takes; the rest is said", () => { const { timeline, errors } = readTimeline({ fps: 1, diff --git a/tools/manual-ref/cli.ts b/tools/manual-ref/cli.ts index 4ec21161c..8eab1ca8b 100644 --- a/tools/manual-ref/cli.ts +++ b/tools/manual-ref/cli.ts @@ -26,7 +26,7 @@ const verbs: Verb[] = JSON.parse(run(["help", "--json"])).verbs // the index's groups, in the order a reader meets them; every verb is in one const GROUPS: [string, string, string[]][] = [ ["Make", "Render, play and package what you wrote.", ["render", "play", "export-game", "export", "bundle", "app", "run"]], - ["Projects", "The workspace, its projects and what a project holds.", ["init", "workspace", "project", "controller", "spec", "component", "part", "add", "brand", "library", "index"]], + ["Projects", "The workspace, its projects and what a project holds.", ["init", "workspace", "project", "spec", "component", "part", "add", "brand", "library", "index"]], ["Check", "What's wrong before anyone watches it.", ["check", "judge", "fingerprint", "findings", "scene", "light", "world", "solid", "next", "doctor", "hook", "traces"]], ["Footage", "Takes, cuts and the camera, from your own media.", ["media", "cut", "frame", "track", "splat", "mezz", "neural"]], ["Sound", "Music read, foley and instruments made on this machine.", ["song", "sounds", "sao", "tokensynth", "setup-audio"]], diff --git a/tools/no-void.sh b/tools/no-void.sh index 179bd6650..aeedc86c5 100755 --- a/tools/no-void.sh +++ b/tools/no-void.sh @@ -23,7 +23,8 @@ SHIMS=(':!systems/ml/src/feed.rs') # a recorded SEO rankings file (the keywords searched that day) # P26 baseline rows already taken (their notes name the composition as it was then) RECORDS=(':!*-OFL.txt' ':!apps/site/seo/rankings/*' ':!bench/p26-baseline/manifest.jsonl') -SKIP=("${SHIMS[@]}" "${RECORDS[@]}" ':!*.lock' ':!*pnpm-lock.yaml' ':!*package-lock.json' ':!*/vendor/*' ':!vendor/*' ':!**/node_modules/**' ':!tools/no-void.allow' ':!tools/no-void.sh' ':!docs/handoff/*' ':!docs/overhaul/audit/*' ':!*LICENSE*' ':!*LICENCE*' ':!*.png' ':!*.jpg' ':!*.mp4' ':!*.woff2' ':!*.glb' ':!*.wasm') +# raea-skills (skills/) is its own repo: an export has its files, the live tree's git grep never reads them +SKIP=("${SHIMS[@]}" "${RECORDS[@]}" ':!skills/*' ':!*.lock' ':!*pnpm-lock.yaml' ':!*package-lock.json' ':!*/vendor/*' ':!vendor/*' ':!**/node_modules/**' ':!tools/no-void.allow' ':!tools/no-void.sh' ':!docs/handoff/*' ':!docs/overhaul/audit/*' ':!*LICENSE*' ':!*LICENCE*' ':!*.png' ':!*.jpg' ':!*.mp4' ':!*.woff2' ':!*.glb' ':!*.wasm') # file:line of each use, in one repo (prefixed with its path in raea) uses() { diff --git a/tools/size.sh b/tools/size.sh index f4a85adfa..310f309aa 100755 --- a/tools/size.sh +++ b/tools/size.sh @@ -13,10 +13,11 @@ cd "$ROOT" || exit 2 FILE_MAX=${FILE_MAX:-500} CRATE_MAX=${CRATE_MAX:-2000} ALLOW=tools/size.allow -# code only; vendored crates are upstream's, lockfiles and type declarations are generated, and so is a file whose first +# code only (raea-skills, skills/, is its own repo: an export has its files, the live tree's git doesn't list them); +# vendored crates are upstream's, lockfiles and type declarations are generated, and so is a file whose first # line says it was ("// Generated by ...": its generator checks it for drift, and nobody edits it) files() { - git ls-files --cached --others --exclude-standard -- '*.rs' '*.ts' '*.tsx' '*.mjs' '*.js' '*.sh' ':!vendor/*' ':!*/vendor/*' ':!**/node_modules/**' ':!*.d.ts' \ + git ls-files --cached --others --exclude-standard -- '*.rs' '*.ts' '*.tsx' '*.mjs' '*.js' '*.sh' ':!vendor/*' ':!*/vendor/*' ':!**/node_modules/**' ':!*.d.ts' ':!skills/*' \ ':!*.min.js' | while read -r f; do [ -f "$f" ] && ! head -1 "$f" | grep -qi '^// generated by' && echo "$f"; done } # "lines path" per file over FILE_MAX diff --git a/tools/skills.sh b/tools/skills.sh index ae9422ce5..ec50d5d5c 100755 --- a/tools/skills.sh +++ b/tools/skills.sh @@ -125,7 +125,7 @@ gen_feed() { "", "The tools the raea app offers every agent it launches, as the MCP server `feed` (apps/app host/acp/feed-mcp.ts).", "PAGE: the feed'"'"'s page answers it, so the app must be open (or a windowless page); PERSON: a click finishes it.", - "With no page, use the CLI instead: `raea controller` for the controllers, `raea context .` for the brief.", + "With no page, use the CLI instead: `raea context .` for the brief and the taste, `raea check` for the rules.", "", (.[] | "## \(.name)", "", @@ -205,8 +205,8 @@ gen_files() { echo "## The spec files" echo echo "Each spec's fields, as raea/brief's types (sdk/raea/src/brief.gen.ts, generated from the schemas in core/brief that" - echo "\`raea spec\` checks against): brief.ts is a Brief, NAME.script.ts a Script, taste.ts a Taste, plan.ts a Plan and" - echo "controllers/ID.ts a Controller. A field marked ? may be left out." + echo "\`raea spec\` checks against): brief.ts is a Brief, NAME.script.ts a Script, taste.ts a Taste and plan.ts a Plan." + echo "A field marked ? may be left out." echo echo '```ts' grep -v '^// Generated' "$ROOT/sdk/raea/src/brief.gen.ts" | sed '/^$/d'