{"record":{"id":"f278be2a18223d6d","repo":"sinelaw/fresh","slug":"no-api-declarations-found-in-start-the-editor-once-to-write","errorCode":null,"errorMessage":"no API declarations found in {} — start the editor once to write them","messagePattern":"no API declarations found in (.+?) — start the editor once to write them","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/fresh-editor/src/main.rs","lineNumber":4475,"sourceCode":"        }\n    }\n    entries\n}\n\n/// Where the API declarations live, and their contents.\nfn read_api_declarations() -> AnyhowResult<Vec<(String, String)>> {\n    let dir = fresh::config_io::DirectoryContext::from_system()?\n        .config_dir\n        .join(\"types\");\n    let mut out = Vec::new();\n    for file in [\"fresh.d.ts\", \"plugins.d.ts\"] {\n        let path = dir.join(file);\n        if let Ok(text) = std::fs::read_to_string(&path) {\n            out.push((file.to_string(), text));\n        }\n    }\n    if out.is_empty() {\n        anyhow::bail!(\n            \"no API declarations found in {} — start the editor once to write them\",\n            dir.display()\n        );\n    }\n    Ok(out)\n}\n\n/// `fresh --cmd script api <query>` — find API members by name or description.\n///\n/// The alternative is grepping a 4000-line declaration file, where a search for\n/// \"split\" returns every unrelated sense of the word. Matching the name first\n/// and the prose second puts the verb you meant at the top, and printing each\n/// hit with its doc comment means one call usually answers the question\n/// outright.\nfn script_api(query: &str, flags: &[&str]) -> AnyhowResult<()> {\n    let json = flags.contains(&\"--json\");\n    let needle = query.to_lowercase();\n    let files = read_api_declarations()?;","sourceCodeStart":4457,"sourceCodeEnd":4493,"githubUrl":"https://github.com/sinelaw/fresh/blob/67894ca5463dbd7a89bb31add4627c27d6b79d83/crates/fresh-editor/src/main.rs#L4457-L4493","documentation":"When collecting API declaration files from the declarations directory, none could be read, so the client bails telling you to start the editor once — the editor writes the .d.ts-style declaration files on first launch. Without them, script authoring/typechecking has no API surface to work from.","triggerScenarios":"Running the declarations-consuming subcommand (e.g. script typecheck/authoring flow) before ever launching the editor, pointing at the wrong declarations directory, or the directory existing but all reads failing.","commonSituations":"Fresh install where the editor has never run; FRESH_CONFIG/HOME pointing elsewhere so the tool looks in the wrong dir; declarations cleaned by a cleanup script or never written due to an earlier startup failure.","solutions":["Start the Fresh editor once so it writes its API declaration files, then rerun the command.","Check you are pointing at the correct declarations directory (the one printed in the message).","If the editor was started but files are still missing, check editor logs for declaration write failures and fix permissions on the directory.","Reinstall/repair Fresh if the editor repeatedly fails to emit declarations."],"exampleFix":"# before\nfresh --script-check myscript.js   # declarations never generated\n# after\nfresh main.rs          # first launch writes API declarations\nfresh --script-check myscript.js","handlingStrategy":"fallback","validationCode":"const fs = require('fs');\nconst path = require('path');\nconst dir = path.join(process.env.HOME, '.config/fresh/declarations');\nconst has = fs.existsSync(dir) && fs.readdirSync(dir).some(f => f.endsWith('.d.ts'));\nif (!has) { console.error(`no declarations in ${dir}; start the editor once first`); process.exit(1); }","typeGuard":null,"tryCatchPattern":"// bash\nDECL_DIR=\"$HOME/.config/fresh/declarations\"\nif [ -z \"$(ls \"$DECL_DIR\" 2>/dev/null)\" ]; then\n  echo 'starting editor once to generate API declarations...'\n  fresh --headless-generate-declarations || fresh . && sleep 2\nfi","preventionTips":["Launch the editor once after installing/upgrading Fresh before using script tooling.","Confirm FRESH_CONFIG/HOME so tooling looks in the same directory the editor writes to.","Exclude the declarations directory from cleanup scripts.","Check for write-permission problems if first launch fails to emit declarations."],"tags":["cli","declarations","scripting","first-run"],"backgroundTag":"file-not-found","analyzedSha":"67894ca5463dbd7a89bb31add4627c27d6b79d83","analyzedAt":"2026-09-13T15:04:03.701Z","contentChangedAt":"2026-09-13T15:04:03.701Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}